Onaro™ONARO

Documentation / Integrations / OpenTelemetry Collector

OpenTelemetry Collector connector

Early access. Available to customers now. We confirm the first import with you in a sandbox before production.

Any agent instrumented with the OpenTelemetry GenAI semantic conventions can send its usage to Meridian through your own OpenTelemetry Collector. The open-source OASA exporter (oasa-otel-exporter) turns every span that carries gen_ai.* attributes into an OASA usage record and posts the records in batches to the Meridian events endpoint, where they roll up into the spend ledger under the agent that made the call.

Early accessMethod: API

Overview

Any agent instrumented with the OpenTelemetry GenAI semantic conventions can send its usage to Meridian through your own OpenTelemetry Collector. The open-source OASA exporter (oasa-otel-exporter) turns every span that carries gen_ai.* attributes into an OASA usage record and posts the records in batches to the Meridian events endpoint, where they roll up into the spend ledger under the agent that made the call.

Data pulled

  • One OASA usage record per span with gen_ai.* attributes; the exporter ignores spans without them
  • Provider, model, operation, input, output, cached and reasoning tokens, tool name, agent id and name, conversation id, and trace and span ids
  • Cost center, project, customer, environment and tags when you set them in the exporter's attribution settings
  • No prompts, responses or prices: usage records carry token counts, not message content or cost
  • Stored as agent events with source_system otel-collector, then rolled up into spend_records as source_type=telemetry

What gets attributed

Meridian attributes each record by its agent_id, which the exporter takes from the span attribute gen_ai.agent.id. The first record with a new agent_id adds the agent to your inventory, named from gen_ai.agent.name, and later records with the same id roll up under that agent. Rename it and give it a department on the Agents page.

Spans without gen_ai.agent.id carry only an agent name (the exporter falls back to the resource service.name) and arrive unattributed. They roll up in the attribution inbox (Agents & allocation → Unattributed), where you can assign them by hand. Manual assignments survive later rollups.

The exporter never prices anything. Meridian values each record from your organization's rate card (Settings → Rate cards), then its model price catalog, and records $0 only if neither has the model.

The ledger is grouped by vendor, model, agent and day. Cost center, project, customer, environment and tags from the exporter's attribution settings are stored with the raw event but are not written to the ledger, so they do not drive department reporting today.

Authentication & credential storage

Meridian stores no collector or model provider credentials for this connector. It keeps only:

  • ingest key hash
  • The exporter sends the key as Authorization: Bearer <key>. Create it in Settings → Ingest keys; it carries the meridian:ingest scope only, and meridian:* does not imply it. Keys from the Event ingest settings page are a different kind and are rejected with 401.
  • The key is shown once, when it is created. Keep it in an environment variable or secret store and reference it as ${env:MERIDIAN_INGEST_KEY} in the collector configuration.
  • Revocation: revoke the key in Settings → Ingest keys. The collector then gets 401 and drops batches until you deploy a new key.

Sync schedule & behavior

There is no sync schedule. The exporter sends records as the collector batches them and Meridian stores them on arrival. The rollup into the spend ledger runs every hour at 20 minutes past, in UTC, and looks back 7 days, so a record that arrives more than 7 days after the call is stored but not rolled up.

Setup steps

  1. Create an ingest key in Meridian (Settings → Ingest keys → Create key) and store it as MERIDIAN_INGEST_KEY where the collector runs.
  2. Get a collector that includes the exporter: download the prebuilt otelcol-oasa binary from the v0.1.0 release on GitHub, or add github.com/onaro-io/oasa-otel-exporter v0.1.0 to your ocb manifest with name: oasaexporter.
  3. Configure the oasa exporter with sink: http, endpoint https://api.onaro.io/v1/meridian/events, token ${env:MERIDIAN_INGEST_KEY} and max_batch_size 1000 or lower, and add it to a traces pipeline.
  4. Set gen_ai.agent.id and gen_ai.agent.name on your agent spans so calls attribute to an agent. Optionally map cost center, project and customer attributes under attribution.
  5. Make one instrumented agent call. Check the collector log for rejected records, and call GET https://api.onaro.io/v1/meridian/ingest/health with the same key to confirm last_ingest_at.
  6. After the next rollup (20 minutes past the hour, UTC), find the call under its agent on Agents & allocation, or under Unattributed if the span had no agent id.

Troubleshooting

  • Nothing arrives: confirm the spans carry gen_ai.* attributes and that the oasa exporter is in a traces pipeline. Run it once with sink: file to see the records it writes.
  • 401 or 403: the key is not a meridian:ingest key, was revoked, or has an IP allowlist that excludes the collector. The exporter treats these as permanent and drops the batch; create a key in Settings → Ingest keys and redeploy.
  • Rejected records: Meridian returns 200 for any well-formed batch, even when some records are rejected. The exporter logs a warning with the first rejection reason and does not retry those records.
  • 429 with X-Meridian-Limit-Type: the monthly event ceiling or hard cap is reached. The exporter drops the batch without retry and counts the records in otelcol_exporter_oasa_limit_rejected_records; alert when it is above zero. See Event allowances and rate limits.
  • 429 with Retry-After, 503 or other 5xx: the exporter retries with backoff. Rate limits count requests, not records, so keep max_batch_size near 1,000 and each request carries more records. See Event allowances and rate limits.
  • Calls show as unattributed: the spans had no gen_ai.agent.id. Add it to your instrumentation, or assign the rows by hand in the attribution inbox.
  • Cost is $0: neither your rate card nor the model price catalog has the model name the span reported. Add the model to a rate card.

Related

Onaro Meridian is FinOps for agentic AI: the system of record that attributes, controls and books what AI agents spend.