# Telemio and OpenTelemetry

Telemio is designed to accept standard OpenTelemetry signals. Existing OpenTelemetry instrumentation should usually stay in place.

## Identity

Set stable service/application identity before adding custom spans. At minimum, use `service.name`. Add environment and release/version attributes when the deployment or build system has those values.

Avoid deriving service names from hostnames, pod IDs, device IDs, or other values that change on each deployment or installation.

## Export

Use the normal OTLP exporter for trusted runtimes. The hosted OTLP endpoint is:

```text
https://otlp.telemio.sh
```

Keep privileged authentication values in server environment variables or a secret manager. Do not ship server credentials inside browser or native/mobile binaries; use a client-safe collection path or trusted gateway for distributed clients.

## Runtime strategy

- Node.js/JavaScript/TypeScript services: use standard OpenTelemetry auto-instrumentation; use `@telemio/sdk` only for explicit application/agent context.
- Java/JVM: prefer the OpenTelemetry Java agent or an existing Spring/OpenTelemetry setup, then add manual spans where the application needs them.
- Python, Go, .NET, PHP, Ruby and other service languages: use their standard OpenTelemetry SDK/auto-instrumentation ecosystem and export OTLP.
- Swift/iOS: use the OpenTelemetry Swift implementation and preserve mobile app/release/session context supported by the instrumentation.
- Android/Kotlin/Java: use OpenTelemetry Android/mobile instrumentation and preserve lifecycle, session, network, crash/ANR, and performance context where supported.
- React Native: coordinate JavaScript and native instrumentation so the same network operation is not recorded twice.
- Agentic runtimes: keep standard service instrumentation and add current OpenTelemetry GenAI/tool semantics around model, tool, MCP, retrieval, orchestration, handoff, and durable workflow boundaries.

## Signals

Use traces for request and operation causality, logs for discrete diagnostic records, and metrics for measurements that need aggregation over time. Browser and mobile telemetry should retain session and release context when those runtimes are present.

A single incident often crosses several signals. Keep trace and request identifiers available in logs when the runtime supports correlation.

## Manual instrumentation

Automatic HTTP or database spans are useful because they are consistent and cheap to maintain. Manual spans should name operations that matter to the application, such as `order.fulfill`, `invoice.generate`, or `agent.resolve_ticket`.

Do not wrap every function or method in a custom span. That produces noise and makes instrumentation harder to keep current.

## Agent and model activity

For agents, keep the trace shape useful even when content capture is disabled. Record operation names, model/provider identity, agent/workflow identity, tool names/types, status, token counts, cost metadata, retry counts, handoffs, and stable identifiers or fingerprints where useful.

The OpenTelemetry GenAI conventions evolve. Prefer the current standard semantics over permanent vendor-specific names when the standard covers the operation.

Prompt and completion bodies are not required to understand most latency, cost, failure, and orchestration problems.

## Privacy

Do not send API keys, bearer tokens, cookies, passwords, card details, prompt/tool payloads, or raw secrets as attributes. Review user-supplied content before deciding to export it. Metadata-first instrumentation is the default for agent content.