@usagetap/otel-exporter

Export UsageTap usage metrics to any OpenTelemetry-compatible observability platform.

Installation

npm install @usagetap/otel-exporter @usagetap/sdk

Quick Start

import { UsageTapClient } from "@usagetap/sdk";
import { createOtelExporter } from "@usagetap/otel-exporter";

// Create the OTEL exporter
const otel = createOtelExporter({
  endpoint: "https://otel-collector.example.com:4318/v1/metrics",
  headers: {
    Authorization: "Bearer your-api-key",
  },
  serviceName: "my-llm-service",
});

// Wire it to the UsageTap client
const usageTap = new UsageTapClient({
  apiKey: process.env.USAGETAP_API_KEY!,
  baseUrl: process.env.USAGETAP_BASE_URL!,
  onUsageMetric: otel.send,
});

// Use UsageTap as normal - metrics are automatically exported
const result = await usageTap.withUsage(
  { customerId: "user-123" },
  async (ctx) => {
    // Your LLM call here
    ctx.setUsage({ inputTokens: 100, responseTokens: 50 });
    return "response";
  }
);

// On application shutdown
await otel.shutdown();

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | endpoint | string | Required | OTLP HTTP endpoint URL | | headers | Record<string, string> | {} | Auth headers (API keys, tokens) | | serviceName | string | "usagetap" | Service name in metrics | | serviceVersion | string | "1.0.0" | Service version | | resourceAttributes | Record<string, string> | {} | Additional resource attributes | | exportIntervalMs | number | 60000 | Export batch interval (ms) |

Exported Metrics

| Metric | Type | Description | |--------|------|-------------| | usagetap.calls | Counter | Number of LLM API calls | | usagetap.tokens.input | Counter | Input/prompt tokens | | usagetap.tokens.output | Counter | Output/response tokens | | usagetap.tokens.cached | Counter | Cached tokens | | usagetap.tokens.reasoning | Counter | Reasoning tokens | | usagetap.cost.usd | Counter | Cost in USD | | usagetap.searches | Counter | Web search calls | | usagetap.audio.seconds | Counter | Audio duration | | usagetap.custom_meter | Counter | Custom meter increments |

Metric Attributes

All metrics include these attributes:

• usagetap.customer_id - Customer identifier
• usagetap.call_id - Unique call ID
• usagetap.feature - Feature tag
• usagetap.model - Model used
• usagetap.tags - Comma-separated tags
• usagetap.correlation_id - Trace correlation ID

Platform Examples

Datadog

const otel = createOtelExporter({
  endpoint: "https://http-intake.logs.datadoghq.com/api/v2/otlp/v1/metrics",
  headers: {
    "DD-API-KEY": process.env.DD_API_KEY!,
  },
});

Grafana Cloud

const otel = createOtelExporter({
  endpoint: "https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/metrics",
  headers: {
    Authorization: `Basic ${Buffer.from(`${instanceId}:${apiKey}`).toString("base64")}`,
  },
});

New Relic

const otel = createOtelExporter({
  endpoint: "https://otlp.nr-data.net:4318/v1/metrics",
  headers: {
    "api-key": process.env.NEW_RELIC_LICENSE_KEY!,
  },
});

Self-hosted Collector

const otel = createOtelExporter({
  endpoint: "http://localhost:4318/v1/metrics",
});

License

MIT