Metrics

Push counters and histograms about business events to Dash0 so we can chart, alert, and slice them by attributes — without inflating trace volume or grepping logs.

This page covers how to add a metric correctly. The OTel SDK is already wired in @repo/tracer; you just import and use it.

When to use metrics (vs traces vs logs)

If your question is aggregate (counts, rates, distributions) → metric. If it’s about a specific occurrence → trace or log.

The API

Three things to know.

import { metrics } from "@repo/tracer"
 
// 1. Get a meter — one per domain/package, conventionally the package name.
const meter = metrics.getMeter("@repo/inventory")
 
// 2. Declare counters as module-level constants (NOT inside handlers — would
//    re-register on every call).
const inventoryMutations = meter.createCounter("inventory.mutations", {
  description: "Inventory create/update/delete operations",
})
 
// 3. Call .add() at every event site.
inventoryMutations.add(1, {
  game: gameSlug,      // pokemon / mtg / lorcana / ...
  action: "create",    // create / update / delete
  source: "csv-import" // ui / csv-import / api / admin
})

Counter types

Most cases are counters. Reach for histograms when you need percentiles (p50/p95/p99), and up-down counters when the value can decrement.

Naming conventions

Lowercase, dotted, scoped to a domain. Match how you’d want to filter in Dash0.

Rules:

• <domain>.<event> or <domain>.<sub>.<event>
• Plural events (signups, not signup).
• Include unit in the name only when ambiguous (.duration_ms, .bytes). Counters of events don’t need a unit suffix.
• Errors and successes go in separate metrics, not one metric with a success: true/false attribute. The question “how many failures” is independent of “how many successes” and you’ll want to alert on them differently.

Worked example — “user signs up”

// packages/backend/user/src/auth/signup.service.ts
@injectable()
export class SignupService {
  async signup(input: SignupInput): Promise<Result<User, SignupError>> {
    // ... validate, create user, send welcome email ...
    return ok(user)
  }
}

// packages/backend/user/src/auth/signup.service.ts
import { metrics } from "@repo/tracer"
 
// Module-level — registered once when the file loads.
const meter = metrics.getMeter("@repo/user")
const signupsCounter = meter.createCounter("users.signups", {
  description: "Successful account creations",
})
 
@injectable()
export class SignupService {
  async signup(input: SignupInput): Promise<Result<User, SignupError>> {
    // ... validate, create user, send welcome email ...
 
    signupsCounter.add(1, {
      source: input.source,    // "web" | "mobile" | "discord-oauth"
      country: input.country,  // ISO country code (~250 values — fine)
    })
 
    return ok(user)
  }
}

Two attributes, both bounded enums. Total cardinality: ~3 sources × ~250 countries = ~750 series. Cheap and useful.

If you wanted to track signup failures, that’s a separate counter (users.signup_failures) with attributes like { reason: "email_taken" | "invalid_email" | "rate_limited" } — not a success: false flag on the same counter.

Where to view in Dash0

In Dash0, switch to the dataset that matches your environment (dev / staging / prod), then go to the Metrics explorer. Filter by:

• service.name = "repo/backend" (or "repo/public-api")
• The metric name (e.g. users.signups)

Group by attributes (e.g. source, country) to slice the chart. The standard resource attributes (deployment.environment.name, aws.ecs.task.arn, cloud.region) are attached automatically by the OTel SDK + Collector — no need to set them yourself on the counter.

Local development

Metrics export honors OTEL_SDK_DISABLED=true — same flag that skips the tracer. If you want metrics to flow in local dev:

1. Set OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
2. Run a local OTel Collector pointed at Dash0 (or use the debug exporter to dump metrics to stdout)

Most engineers don’t need this — verify the counter is wired correctly with a unit test or by deploying to dev and checking Dash0.

Adding a new metric — checklist

Code Locations