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

# Telemetry ingest — Observra & OpenTelemetry

> Route agent telemetry you already collect into Cognisafe's safety scoring and governance — no SDK change required.

Cognisafe is the **scoring and governance destination** for your agent
telemetry. If your agents already emit telemetry — via
[Observra](https://github.com/open-agent-ai-security/observra) or any
OpenTelemetry pipeline — you can route it straight into Cognisafe and get
OWASP LLM Top 10 scoring, dashboards, alerts, and audit evidence on that
traffic, without touching your application code.

Both endpoints authenticate with a normal Cognisafe API key and go through
the same pipeline as first-party traffic: tier rate limits, retention
settings (including zero content retention), safety scoring, and alerting
all apply.

## Observra

[Observra](https://open-agent-ai-security.github.io/observra/) is an
open-source agent telemetry SDK (Apache 2.0) covering Google ADK, Claude
Agent SDK, OpenAI Agents SDK, LangChain/LangGraph, and Pydantic AI. Point its
webhook backend at Cognisafe:

```python theme={null}
from observra import initialize

initialize(
    backends=["webhook"],
    webhook_url="https://api.cognisafe.uk/ingest/observra",
    webhook_headers={"X-Cognisafe-Key": "csk_your_key"},
)
```

That's it — every agent framework Observra supports now feeds Cognisafe.

### How events map

| Observra event                                   | What Cognisafe does                                                                                                                 |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `user_message`                                   | Holds the prompt text briefly (10 min), keyed by `session_id`                                                                       |
| `model_response` / `turn`                        | Creates a request, merging the held prompt from the same session — model, tokens, agent name, and prompt all land on one scored row |
| `model_error`                                    | Creates a request carrying the error                                                                                                |
| Everything else (sessions, tool calls, handoffs) | Accepted and ignored (`202`, counted in `ignored`)                                                                                  |

Because Observra redacts PII before events leave your process, what
Cognisafe scores is the redacted text — a good pairing with
[zero content retention](/self-hosting/environment-variables) if you want
no raw content persisted anywhere.

### Request format

`POST /ingest/observra` accepts a single event object or a JSON array
(max 500). Auth via `X-Cognisafe-Key: csk_...` or
`Authorization: Bearer csk_...`.

```json theme={null}
{"accepted": 1, "ignored": 3, "ids": ["<request uuid>"]}
```

## OpenTelemetry

`POST /ingest/otel` accepts OTLP/HTTP **JSON** traces. Any span carrying
[GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
becomes a scored Cognisafe request; other spans are ignored.

Attributes read (first match wins):

| Cognisafe field | GenAI attributes                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------- |
| model           | `gen_ai.request.model`, `gen_ai.response.model`, `gen_ai.system`                                    |
| prompt          | `gen_ai.prompt`, `gen_ai.content.prompt`                                                            |
| response        | `gen_ai.completion`, `gen_ai.content.completion`                                                    |
| tokens          | `gen_ai.usage.input_tokens` / `output_tokens` (and the older `prompt_tokens` / `completion_tokens`) |
| agent           | `gen_ai.agent.name`                                                                                 |
| latency         | span start/end timestamps                                                                           |

Point an OTel Collector at it with an `otlphttp` exporter:

```yaml theme={null}
exporters:
  otlphttp/cognisafe:
    traces_endpoint: https://api.cognisafe.uk/ingest/otel
    headers:
      X-Cognisafe-Key: csk_your_key
    encoding: json
```

<Note>
  Spans without prompt/completion content still produce metadata rows (model,
  tokens, latency, cost) — useful for cost attribution even when your
  pipeline strips content. Scoring runs when content is present.
</Note>

## Choosing an integration path

| You have                                                                   | Use                                                                        |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Direct OpenAI/Anthropic/Mistral/Cohere calls                               | The [Cognisafe SDK](/sdk/python) or [proxy](/quickstart) — richest capture |
| Agents on ADK / Claude Agent SDK / OpenAI Agents / LangChain / Pydantic AI | Observra → `/ingest/observra`                                              |
| An existing OTel pipeline with GenAI spans                                 | Collector → `/ingest/otel`                                                 |