# Instrument a repository with Telemio

Use this guide when a coding agent is responsible for adding Telemio observability to an existing repository.

## Goal

Add production-appropriate telemetry with OpenTelemetry as the default instrumentation layer. Cover every runtime that actually executes, including services, browsers, native/mobile applications, JVM processes, and agentic runtimes. Use Telemio-specific code only where it adds useful application or agent context.

## Work through the repository in this order

1. Identify every runtime that actually executes: API servers, workers, cron jobs, serverless/edge functions, browsers, Swift/iOS apps, Android/Kotlin/Java apps, React Native, CLIs, JVM services, .NET/C#, Python, Go, PHP, Ruby, Rust, C/C++, Erlang/Elixir, desktop apps, queues, Kubernetes workloads, GPU/model servers, and AI/agent processes.
2. Find existing telemetry before adding anything. Preserve working OpenTelemetry configuration and extend it instead of creating a parallel stack.
3. Prefer official OpenTelemetry SDKs, zero-code agents, and auto-instrumentation for HTTP, frameworks, databases, queues, runtime metrics, and supported mobile signals.
4. For Java/JVM services, prefer the OpenTelemetry Java agent or the project's existing Java/Spring OpenTelemetry setup before custom instrumentation.
5. For native/mobile applications, use platform OpenTelemetry instrumentation and keep privileged Telemio server credentials out of distributed app bundles.
6. Give every process a stable `service.name`. Add environment and release identity using the repository's existing deployment/build configuration. Preserve app version/build identity on mobile clients.
7. Configure OTLP export to Telemio through trusted server configuration, a collector/gateway, or an appropriate client-safe ingestion path.
8. Add manual spans around business operations only where automatic spans are too generic. Good examples are checkout creation, job fulfillment, document indexing, or an agent workflow.
9. Treat agentic runtimes as first-class runtimes. Record model calls, agent/workflow runs, tools, MCP operations, retrieval, token usage, errors, retries, handoffs, durable/background work, and outcome metadata. Follow current OpenTelemetry GenAI semantics where they apply.
10. Do not copy prompts, completions, tool payloads, retrieved private content, source code, credentials, cookies, authorization headers, payment information, or sensitive personal data into telemetry by default.
11. Preserve trace context across service calls, queues, jobs, mobile/browser requests, and agent handoffs where possible.
12. Run the repository's normal tests, builds, linters, type checks, and platform checks.
13. Report what changed, what configuration is required, which runtimes are covered, and any gaps that still need manual work.

## CLI

```bash
npm i -g telemio
telemio detect
telemio setup auto
telemio setup collector
```

Use `telemio help` to see the available setup helpers.

## JavaScript and TypeScript manual instrumentation

```bash
npm i @telemio/sdk
```

```ts
import { createTelemio } from "@telemio/sdk"

const telemio = createTelemio({
  apiKey: process.env.TELEMIO_API_KEY,
  serviceName: "checkout-api",
  environment: process.env.NODE_ENV,
  release: process.env.APP_VERSION
})

await telemio.tracer.withSpan("checkout.create", async (span) => {
  span.setAttribute("checkout.provider", "stripe")
  await createCheckout()
})
```

The SDK defaults to `https://api.telemio.sh`. Keep server API keys out of browser and native/mobile bundles.

## Hosted ingestion credentials

The MCP credential and the workload ingest credential are different secrets. MCP lets the coding agent inspect and manage the Telemio workspace. A trusted server or Collector uses a workspace-scoped ingest credential to send live telemetry.

If hosted ingestion is blocked because no ingest credential is available, do not ask the user to paste one into the agent conversation. Return `TELEMIO_INGEST_STATUS: NEEDS_CREDENTIAL` and tell the user which server-side secret name or secret-manager location the workload should consume. The Telemio console can generate an ingest-only `tmio_ingest_...` credential and a safe local handoff script.

For server-side OTLP, use `https://otlp.telemio.sh` and source the `x-api-key` header from `TELEMIO_API_KEY`. If the application already sends to a local OpenTelemetry Collector, keep the application credential-free and let the trusted Collector add the Telemio credential when forwarding.

## Runtime-specific references

- Native/mobile: https://telemio.sh/agent/native-mobile.md
- Polyglot runtimes: https://telemio.sh/agent/polyglot-runtimes.md
- Serverless and edge: https://telemio.sh/agent/serverless-edge.md
- Collector: https://telemio.sh/agent/collector.md
- Kubernetes: https://telemio.sh/agent/kubernetes.md
- Messaging: https://telemio.sh/agent/messaging.md
- Desktop: https://telemio.sh/agent/desktop.md
- GPU/inference: https://telemio.sh/agent/gpu-inference.md
- Profiles: https://telemio.sh/agent/profiles.md
- Client-safe ingest: https://telemio.sh/agent/client-ingest.md
- Java/JVM: https://telemio.sh/agent/jvm.md
- Agentic runtimes: https://telemio.sh/agent/agentic-runtimes.md
- OpenTelemetry: https://telemio.sh/agent/opentelemetry.md
- Telemio SDK: https://telemio.sh/agent/sdk.md

## Finish with a short instrumentation report

Include:

- runtimes found
- auto/zero-code instrumentation added or reused
- manual spans/events added
- environment variables, gateways, or client-safe configuration required
- tests and builds run
- telemetry intentionally excluded for privacy
- remaining instrumentation gaps