How telemetry reaches Trefur

Trefur supports five ingest paths. All emit identical payloads to the same backend — pick the one that fits your runtime, or combine them.

The five paths

                          ┌────────────────────────────────┐
                          │            Trefur              │
                          │  observe.trefur.com / api.…    │
                          └──────────────▲─────────────────┘
                                         │ HTTPS, gzip, retry
              ┌──────────────────────────┼──────────────────────────┐
              │                          │                          │
        ┌─────┴──────┐          ┌────────┴────────┐         ┌───────┴────────┐
        │  SDK       │          │  trefur         │         │  OAuth-based   │
        │  direct    │          │  collector      │         │  platform      │
        │            │          │  (single bin)   │         │  discovery     │
        └────────────┘          └─────────────────┘         └────────────────┘
              ▲                          ▲                          ▲
              │                          │ 8 inputs                 │ 16 platforms
              │                          │                          │
  in-process patch              OTLP / LLM proxy /          OAuth into Google
  (Anthropic, OpenAI,           MCP proxy / shell           Workspace, M365,
  LangChain, …)                 hook / exec wrap /          OpenAI Admin, …
                                CDP proxy / HTTP

        ┌────────────┐                                      ┌────────────────┐
        │  Webhook   │                                      │  OTel          │
        │  ingest    │                                      │  forwarder     │
        └────────────┘                                      └────────────────┘
              ▲                                                     ▲
              │ push from anywhere                                  │ from your
              │                                                     │ existing OTel
              │                                                     │ pipeline

Two ingest hostnames, one backend. Language SDKs send to observe.trefur.com by default (override with the endpoint option or TREFUR_ENDPOINT). The collector and any raw OTLP forwarder send to the standard OTLP paths under api.trefur.com — /v1/traces, /v1/metrics, /v1/logs. Both terminate at the same backend and produce identical data, so the choice is only about how you emit, never about where the data lands. The console — where you view it all — is app.trefur.com.

1. SDK direct

Pick the SDK for your language, call init(), and every Anthropic / OpenAI / LangChain / CrewAI / Vercel AI / MCP call is instrumented automatically.

When to pick it: single-process app, in-process control of code, framework auto-instrumentation. Latency: zero added (asynchronous batch flush). Fidelity: highest — exact call args, full message arrays. Attribution: exact (the SDK runs inside your code, so identity is unambiguous).

Read more: JS, Python, Go, Rust, Java, .NET.

2. trefur collector (single binary, 8 inputs)

A single binary you run alongside your agent fleet. Eight ingest paths in one process:

Plus a cloud-authored pipeline DSL: rules authored in the Trefur dashboard (drop / mask / extract / route / enrich) are pulled to the collector every 60s and applied before data leaves your network. The same rules re-apply cloud-side as defense in depth.

Install: brew install trefur-ai/tap/trefur-collector, or download the latest binary from GitHub Releases (Linux / macOS / Windows for amd64 + arm64), or pull the container at ghcr.io/trefur-ai/trefur-collector:latest, or use the one-liner curl install. Init wizard at trefur init.

When to pick it: multi-language fleet, telemetry from agents you do not own (third-party CLIs, MCP servers, headless browser automation), local-buffer-before-egress requirements, OS-level shell capture, or a data-sovereignty story (PII never crosses the prem boundary).

Read more: collector reference.

3. OAuth-based platform discovery

Connect Trefur to platforms your team already uses. We pull activity via official admin APIs — no code change needed by the agents themselves.

• Google Workspace — Reports API (Gemini in Workspace apps), OAuth-grants scanner, Vertex AI Cloud Audit Logs filter for aiplatform.googleapis.com + Cloud Assist cloudaicompanion.googleapis.com
• Microsoft 365 — Microsoft Graph audit logs, Copilot prompt counts
• OpenAI Admin API — org + per-user usage
• Anthropic Admin API — workspace + per-key usage
• Slack / Atlassian / Zendesk / HubSpot / Intercom / Salesforce — bot + integration activity
• GCP / AWS / Azure — cloud-native AI service usage
• Snowflake / Databricks — warehouse-resident agent + model usage

When to pick it: you want to see every AI agent in your org — including ones built outside your engineering team — and you cannot add an SDK or collector to every endpoint. Pairs well with the SDK for the agents you own + OAuth discovery for the rest.

Read more: integrations index.

4. Webhook ingest

Some systems already push events out — webhook delivery from a third- party agent platform, a workflow engine, a custom system. Configure a webhook in the Trefur dashboard, copy the signed URL, and point the sender at it. Trefur validates the HMAC signature, normalises the payload into a step, and ships it through the same pipeline as everything else.

When to pick it: the source pushes (it does not pull, and you cannot run an SDK or collector inside it).

5. OTel forwarder

If you already emit OpenTelemetry to another backend, the cheapest path is to add Trefur as a second OTel exporter — no new SDK, no new agent. Point any OTLP/HTTP exporter at:

• Standard OTLP/HTTP (JSON): https://api.trefur.com/v1/traces, https://api.trefur.com/v1/metrics, https://api.trefur.com/v1/logs. Stock OpenTelemetry exporters default to binary protobuf, so set OTEL_EXPORTER_OTLP_PROTOCOL=http/json to send JSON to these endpoints.
• Running the collector locally? Point your exporter at its OTLP/HTTP receiver instead: http://localhost:4318/v1/traces (and the /v1/metrics / /v1/logs siblings).

Authenticate with Authorization: Bearer trf_obs_.... Or run a local trefur collector with both your existing exporter and Trefur as upstreams.

When to pick it: you already have an OTel pipeline and adding a second exporter is the path of least resistance.

Quick-decision matrix