Skip to Content
UsageMapDocs
API analytics

API analytics

Send standard OpenTelemetry metrics from your API and see requests, errors and latency per route. For Node.js and Python, environment variables are enough.

UsageMap reads the standard HTTP server metric that every OpenTelemetry SDK already produces (http.server.request.duration). You don't add a vendor SDK, and your code stays the same.

Before you start

Register the service. In your project, open API services → Register an API service. The service name must match your OTEL_SERVICE_NAME.

Create an ingest token. Open Ingest tokens, create one (optionally limited to this service) and copy it. It starts with scfa_ing_ and is shown only once, so store it in your secret manager.

Connect your API

No code change. Install two packages:

npm install --save-exact @opentelemetry/auto-instrumentations-node@0.83.0 @opentelemetry/instrumentation@0.301.1

Then start your app like this:

OTEL_SERVICE_NAME=my-api \
OTEL_EXPORTER_OTLP_ENDPOINT=https://e1.usagemap.dev \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${USAGEMAP_TOKEN}" \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_METRICS_EXPORTER=otlp OTEL_TRACES_EXPORTER=none OTEL_LOGS_EXPORTER=none \
OTEL_RESOURCE_ATTRIBUTES="service.instance.id=${HOSTNAME}" \
node --experimental-loader=@opentelemetry/instrumentation/hook.mjs \
  --import @opentelemetry/auto-instrumentations-node/register app.mjs

For CommonJS apps, drop the --experimental-loader line and use --require instead of --import.

Edge runtimes and Stellar SDK calls

Both packages below are not yet on the public npm registry. Until they are, use the environment variables above on servers.

@scf-analytics/edge-otel wraps a fetch-style handler (Cloudflare Workers, Vercel Edge, Next.js route handlers, Deno, Bun) and exports the same request metric, with route templates, without an OpenTelemetry SDK:

worker.ts
import { optionsFromEnv, withUsageMap } from "@scf-analytics/edge-otel";
import app from "./app";

export default withUsageMap(app, (env) => ({
  ...optionsFromEnv(env), // wrangler secret put OTEL_EXPORTER_OTLP_HEADERS
  routes: ["/.well-known/stellar.toml", "/auth", "/sep24/transactions/:id"],
}));

The export never delays the response. If the configuration is missing or invalid, the wrapper switches itself off and your handler runs unchanged.

Java, .NET, Next.js?

Any OpenTelemetry SDK that exports the HTTP server duration metric over OTLP/HTTP works. Already exporting to an APM such as Datadog, Grafana or Honeycomb? Send a copy to UsageMap.

Test with curl

Send one data point by hand, without touching your app. A 200 means accepted; it appears on the API dashboard within about two minutes as the route /curl-test.

curl -sS -i https://e1.usagemap.dev/v1/metrics \
  -H "Authorization: Bearer $USAGEMAP_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"resourceMetrics":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"my-api"}},{"key":"service.instance.id","value":{"stringValue":"curl-test"}}]},"scopeMetrics":[{"scope":{"name":"curl-test"},"metrics":[{"name":"http.server.request.duration","unit":"s","histogram":{"aggregationTemporality":1,"dataPoints":[{"attributes":[{"key":"http.request.method","value":{"stringValue":"GET"}},{"key":"http.route","value":{"stringValue":"/curl-test"}},{"key":"http.response.status_code","value":{"intValue":"200"}}],"startTimeUnixNano":"'$(( $(date +%s) - 60 ))000000000'","timeUnixNano":"'$(date +%s)000000000'","count":"1","sum":0.012,"bucketCounts":["0","1","0"],"explicitBounds":[0.005,0.025]}]}}]}]}]}'

The Integration kit in the app gives you this command with your own service name filled in.

What is kept

Kept

Service name and instance, environment, route, HTTP method, status code, duration.

Dropped before storage

Every other metric and attribute, logs, query strings, headers and request bodies.

Rewritten

Stellar accounts and contracts in paths become {account} and {contract}; secrets, tokens and e-mails become {redacted}.

Limits

Up to 50 requests per second per project, 4 MiB per request (compressed). Over the limit you get 429 with Retry-After, and SDKs retry by themselves.

The API dashboard's Data quality section shows exactly what was received and what was dropped, and why.

On this page