Browse documentation

Instrument

Record application metrics

Choose the right metric type, emit low-cardinality measurements, and verify that Anectico can query them.

Metrics show how a system changes over time. Use them for service-wide state such as request volume, queue depth, latency, saturation, and completed work. Use traces, logs, errors, and events when you need the story of one request or customer.

Use a project-scoped API key with ingest:write. Metrics are sent through OTLP and normally export on an interval, so they may appear later than an immediately flushed span or error. Anectico preserves the OTLP temporality and point start timestamp. Delta points are aggregated directly; cumulative monotonic sums and histograms are converted to reset-safe increments before a query aggregates them. This keeps periodic cumulative exports from counting the same work or observations repeatedly.

Choose the measurement type

Type Use it for Example Useful views
Counter A total that only increases Completed orders, bytes sent Change over time, totals
Gauge The latest level can rise or fall Queue depth, memory in use avg, min, max, latest value
Histogram A distribution of observations Request duration, payload size Native histogram or heatmap
Summary Pre-aggregated count, sum, and quantiles An existing OTLP summary Scalar trend; prefer histograms for new instrumentation

Choose the type when you create the OpenTelemetry instrument. Do not turn a current level into a counter or record a duration as a gauge merely because the helper is convenient.

Anectico’s SDK convenience methods deliberately stay small, but their instrument types differ:

  • JavaScript recordMetric records one histogram observation.
  • Python record_metric and Go RecordMetric record a gauge value.
  • Python’s client.meter and Go’s client.Meter() expose the OpenTelemetry Meter when you need an explicit counter, histogram, or other instrument.
  • For JavaScript instrument types beyond the histogram helper, keep or add an OpenTelemetry metrics pipeline and export it to Anectico.

Record one recognizable metric

The following examples use stable labels and avoid customer or request identifiers.

JavaScript / TypeScript

const startedAt = performance.now();
await processCheckout();

anectico.recordMetric('checkout.duration_ms', performance.now() - startedAt, {
  route: '/checkout',
  result: 'success',
});

This records a histogram observation. The client must already be started.

Python

client.record_metric(
    'checkout.queue_depth',
    queue.qsize(),
    labels={'region': 'eu-west', 'worker_pool': 'payments'},
)

This records a gauge value. The client must already be started.

Go

client.RecordMetric("checkout.queue_depth", float64(queueDepth), map[string]string{
	"region":      "eu-west",
	"worker_pool": "payments",
})

This records a gauge value. The client must already be started.

For example, create an explicit Go counter when a gauge would have the wrong meaning:

counter, err := client.Meter().Int64Counter(
	"checkout.orders",
	metric.WithUnit("{order}"),
)
if err != nil {
	return err
}
counter.Add(ctx, 1, metric.WithAttributes(
	attribute.String("result", "success"),
))

Reuse instruments instead of creating them inside a high-frequency request loop. The JavaScript and Go convenience methods cache instruments by name. Python’s convenience method creates the gauge through its Meter on each call, so create and retain an explicit client.meter instrument for a hot path. Instruments you create through an OpenTelemetry Meter are your application’s responsibility.

Send an existing OpenTelemetry pipeline

Anectico accepts OTLP gauges, monotonic and non-monotonic sums, explicit-bucket histograms, and summaries at /v1/metrics. Point your exporter or Collector at https://api.anectico.com, set the X-Anectico-API-Key header, and keep these resource attributes consistent:

Resource attribute Why it matters
service.name Identifies the emitting service and powers service grouping
deployment.environment Keeps production, staging, and development distinct

Use the normal OpenTelemetry SDK lifecycle for your language. A short-lived process must force a metric collection and shut down its Meter Provider or Anectico client before exiting; waiting only for a trace flush does not guarantee that a periodic metric reader has exported.

See Configure OpenTelemetry for the endpoint and authentication configuration.

Keep names, units, and labels stable

  • Label maps are unordered: the same key/value pairs identify the same Anectico metric series regardless of the order in which an SDK or exporter sends them.
  • Give the metric one durable dotted or semantic-convention name. Put dimensions in labels, not in generated metric names.
  • Keep the OpenTelemetry unit correct for pipeline portability. Anectico dashboard widgets currently set their display unit separately; if a convenience helper has no unit argument, make the unit unambiguous in the name, such as checkout.duration_ms.
  • Prefer labels such as route template, result, region, queue, provider, or worker pool.
  • Never use email, customer ID, order ID, request ID, trace ID, session ID, raw URL, or another effectively unique value as a metric label.
  • Keep label keys and their meaning consistent across services. environment=prod and deployment=production create different series and make comparison harder.

Every distinct combination of metric name, service, environment, and labels is an active metric series. A label with unbounded values can create thousands of series, raise usage, and make grouped queries unusable. Customer identity belongs on traces, logs, errors, and events; use those signals to explain which people a metric change affected.

Explore → Metrics shows the organization-wide active-series count and limit. It is not scoped to the selected project, and the background usage snapshot may lag by a few minutes. At the limit, Anectico continues to ingest datapoints for existing series but rejects unseen metric names or label combinations. That rejection is non-retryable; reduce cardinality or raise the limit before sending the new series.

Verify the complete path

  1. Record a metric named anectico.verification.value with value 1 and label check=setup.
  2. Wait for one metric export interval, then flush or stop the client or Meter Provider cleanly.
  3. Select the expected project and environment in Anectico.
  4. Open Explore → Metrics, choose anectico.verification.value, use Last 1 hour, and refresh.
  5. Confirm the CLI sees the same name and a recent point:
anectico metrics list
anectico metrics query anectico.verification.value --agg avg

After verification, stop emitting the test metric. Historical points remain until retention removes them; deleting a metric is an administrative, destructive operation that removes every datapoint in the credential’s effective scope.

If the metric does not appear

  • Confirm metrics are enabled in the SDK or OpenTelemetry pipeline.

  • Confirm the exporter uses /v1/metrics and a key with ingest:write.

  • Allow for the metric export interval and flush short-lived processes.

  • Check the selected project, environment, and time range.

  • Look at SDK or Collector diagnostics for 401, 403, 413, 429, or export failures.

  • Query the metric name with the CLI to separate ingestion from a dashboard filter problem.

  • Remove customer or request identifiers from labels before sending more data.

  • Explore and compare metrics

  • JavaScript SDK API

  • Python SDK API

  • Go SDK API