> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aixy-gateway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Export gateway telemetry

> Choose the OTLP logs and metrics sent to Datadog, Grafana Cloud, S3, or your own receiver.

Telemetry destinations receive privacy-bounded data derived from completed model requests. Create
and manage them in **Observe → Telemetry exports**. Each destination belongs to one organization and
can include all projects or only a selected set.

## Configure a destination

1. Open **Telemetry exports → Add destination**.
2. Choose Datadog, Grafana Cloud, Amazon S3, or a custom OTLP/HTTP receiver.
3. Enter the destination name, connection details, and credentials requested by the form.
4. Select **Logs**, **Metrics**, or both, and choose the projects to include. An empty project
   filter includes all current and future projects.
5. Save, use **Test** on the destination, and inspect its delivery status.
6. Make a model request and verify the selected signals at the receiver.

Administrators need the corresponding destination permissions and plan entitlement. Destinations
belong to the organization even when their filters select particular projects.

## Choose what to export

Every destination must enable logs, metrics, or both. New destinations default to logs.

| Signal | What arrives | Best for |
| - | - | - |
| **Logs** | One `gateway.usage` OTLP log record per completed model request | Request-level investigation, correlation by request ID, routing and policy decisions, and detailed usage or cost context |
| **Metrics** | Batch-aggregated OTLP delta sums and histograms | Datadog or Grafana dashboards, monitors, rates, latency percentiles, token trends, and spend trends without request-level records |

Choose **Metrics** without **Logs** when you want dashboards and monitors but do not want a
request-level event stream. Choose both when operators need aggregate monitoring and individual
request diagnostics in the same backend.

## Log record contract

The `gateway.usage` log contains the event and request IDs, provider and effective model, route,
status, streaming flag, gateway and upstream timing, token usage, routing attempts, policy outcomes,
content-capture status, and cost attribution when evidence exists. Tenant attribution uses stable
organization, project, team, user, and API-key IDs where available.

`gateway.lifecycle.phase` distinguishes completion observations (`request_completed`) from
intermediate fallback accounting (`provider_attempt`). Correlate them by request ID; an intermediate
attempt does not mean the client request has finished.

Timing logs retain total and non-provider durations. `gateway.base_overhead.duration_ms` is the
observed residual after provider execution and explicitly enabled feature execution. When an
intervention runs, `gateway.features.duration_ms` and `gateway.features.executions_json` report
bounded durations, static names, phases and outcomes. These are accounting-boundary diagnostics;
they do not include all remaining settlement or final response-delivery work.

Prompts, responses, provider credentials, gateway API-key values, user email addresses, request
headers, and arbitrary exception text are never included. Optional Activity content capture is a
separate encrypted pipeline and is never copied into a telemetry destination.

## Metric contract

Metrics are aggregated by matching attributes within each export batch and use delta temporality.
Durations use seconds.

| Metric | Type | Meaning |
| - | - | - |
| `aixy.gateway.request.count` | Delta sum | Completed model requests |
| `aixy.gateway.request.duration` | Delta histogram | End-to-end gateway request duration |
| `aixy.gateway.upstream.duration` | Delta histogram | Time spent waiting for the model provider |
| `aixy.gateway.time_to_first_byte` | Delta histogram | Provider time to first byte when observed |
| `aixy.gateway.token.usage` | Delta sum | Input and output token totals; `gen_ai.token.type=total` is used only when a provider reports no split |
| `aixy.gateway.cost` | Delta sum | Attributed cost in USD; omitted when cost evidence is unavailable |
| `aixy.gateway.base_overhead.duration` | Delta histogram | Observed overhead excluding provider execution and measured optional interventions |
| `aixy.gateway.features.duration` | Delta histogram | Measured optional intervention duration; emitted only when an intervention ran |

Base-overhead and feature histograms use completion observations so one request's intervention
time is not counted again for each fallback attempt. The existing duration metrics retain their
meaning. A deliberately enabled feature can trade additional latency for another benefit; its
execution remains visible alongside the total duration.

Metric attributes include provider, model, route, status code, outcome, streaming, optional service
tier, organization, project, and team. Token points add `gen_ai.token.type`; cost points add
attribution status and source. Metrics deliberately omit event, request, user, and API-key IDs.

<Warning>
  Model and project attributes create separate time series in most observability
  platforms. Scope a destination to the projects you need and review your
  backend's custom-metric pricing and cardinality limits before enabling metrics
  broadly.
</Warning>

## Receiver paths and authentication

Aixy stores a signal-neutral OTLP base endpoint and sends binary protobuf to the standard signal
paths:

* logs: `/v1/logs`
* metrics: `/v1/metrics`

You can paste a base URL or an existing `/v1/logs` or `/v1/metrics` URL; Aixy normalizes it to the
base. Redirects, credentials in URLs, private addresses, and special-purpose addresses are rejected.
DNS is checked again when the exporter connects.

* **Datadog** uses the OTLP intake host for the selected Datadog site and an encrypted `dd-api-key`.
  See [Datadog's OTLP intake documentation](https://docs.datadoghq.com/opentelemetry/setup/otlp_ingest/).
* **Grafana Cloud** uses the stack's OTLP base endpoint and encrypted basic-auth credentials.
* **Custom OTLP/HTTP** sends to a public collector or receiver with optional encrypted headers.
* **Amazon S3** stores gzip-compressed OTLP JSON below
  `signal=<logs|metrics>/year=YYYY/month=MM/day=DD/hour=HH/`.

The **Test** action sends one connection-test payload to every selected signal. The test succeeds
only when all selected paths accept their payload.

## Delivery guarantees

Model requests perform one non-blocking enqueue and never wait for a customer receiver. Each
destination has an isolated bounded queue and bounded retries, so one unavailable receiver cannot
delay model traffic or another organization's export.

Delivery is best effort. Queue saturation, process failure, or a prolonged receiver outage can drop
events. Delivery has no durable replay guarantee. The destination health
and delivered/failed counters describe exporter attempts; they are not a billing ledger.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.