# Telemio agent reference

Telemio is an OpenTelemetry-first observability product for application services, browser sessions, native/mobile apps, infrastructure, and agentic runtimes. The preferred setup is to keep standard OpenTelemetry instrumentation wherever it already works, then add Telemio-specific context where an application needs clearer business, product, or agent semantics.

## Installation

CLI:

    npm i -g telemio

First-party JavaScript/TypeScript SDK:

    npm i @telemio/sdk

The SDK is published at https://www.npmjs.com/package/@telemio/sdk.

Useful CLI commands include `telemio setup otel`, `telemio setup rum`, `telemio setup prometheus`, `telemio setup statsd`, and `telemio agent-prompt`.

## Hosted endpoints

Product: https://telemio.sh/
Console: https://console.telemio.sh/
API and SDK default endpoint: https://api.telemio.sh
OTLP ingestion for trusted/server-side exporters: https://otlp.telemio.sh
MCP: https://mcp.telemio.sh

## Repository instrumentation policy

First inspect the repository. Identify the services, clients, native apps, workers, JVMs, and agentic processes that actually run. Reuse existing telemetry instead of adding a second instrumentation path. Prefer official OpenTelemetry SDKs, auto-instrumentation, and zero-code agents. Configure stable service/application, environment, and release/build identity. Add manual spans only around operations that are meaningful to the application and difficult to understand from automatic spans alone.

Correlate traces, logs, metrics, errors, browser/mobile sessions, infrastructure context, and agent operations where the runtime supports it. Instrument databases, queues, HTTP or gRPC dependencies, cloud SDKs, runtime metrics, and background jobs through standard instrumentation when possible.

Keep secrets and sensitive content out of telemetry. Never add credentials, bearer tokens, cookies, card data, passwords, source code, prompt/tool payloads, retrieved private content, or secret configuration as attributes by default. AI content capture should stay metadata-only unless a deliberate product requirement and policy says otherwise.

## Runtime matrix

### Node.js / JavaScript / TypeScript

Use standard OpenTelemetry automatic instrumentation for framework, HTTP, database, queue, and runtime coverage. Add `@telemio/sdk` on trusted server-side runtimes when you need explicit business spans/events, agent context, feature flags, experiments, or context fingerprints.

Do not embed privileged Telemio server keys into browser bundles or distributed client binaries.

### Java and JVM

Prefer the OpenTelemetry Java agent or the project's existing Java/Spring OpenTelemetry setup. The Java agent can provide broad zero-code coverage around server requests, HTTP clients, databases, messaging, and other common libraries. Add manual OpenTelemetry spans only around domain operations that need clearer names.

Keep JVM/process runtime metrics beside application traces when available.

Reference: https://telemio.sh/agent/jvm.md

### Python, Go, .NET, PHP, Ruby and other service languages

Use the standard OpenTelemetry SDK and auto/zero-code instrumentation available for that language/runtime. Export OTLP from trusted infrastructure. Telemio does not require a vendor SDK in every language.

### Swift and iOS

Use OpenTelemetry Swift/mobile instrumentation. Initialize early, preserve application version/build identity, session and network context, and propagate trace context into backend requests where possible. Keep privileged server credentials out of the shipped app.

Reference: https://telemio.sh/agent/native-mobile.md

### Android, Kotlin and Java mobile

Use OpenTelemetry Android/mobile instrumentation. Preserve lifecycle, session, app version/build, network, crash/ANR, and rendering/performance context where supported. Use offline/lifecycle-aware buffering when the chosen instrumentation supports it. Keep privileged server credentials out of APK/AAB binaries.

Reference: https://telemio.sh/agent/native-mobile.md

### React Native

Treat the JavaScript and native runtime layers as related instrumentation surfaces. Avoid recording the same network operation twice. Preserve shared session/trace identity and use native instrumentation where it provides better lifecycle/performance context.

### Browser

Preserve route/page, session, release, error, and performance context. Use a client-safe collection path. Never ship privileged server API keys in frontend JavaScript.

### Serverless and edge

Initialize telemetry as early as the platform permits, preserve cold-start/runtime context when useful, flush within platform lifecycle limits, and keep server credentials in protected environment configuration. `@telemio/sdk` can be used in trusted JavaScript/TypeScript edge runtimes when the environment provides the required web APIs.

## JavaScript/TypeScript SDK

Create a client:

    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
    })

The SDK defaults to https://api.telemio.sh.

The main surfaces are `tracer`, `logger`, `metrics`, `track`, `agent`, `context`, `flags`, and `experiments`. The package also exposes an OpenFeature-compatible provider.

Use standard OpenTelemetry auto-instrumentation before adding manual SDK calls. Manual spans work best around business operations such as checkout creation, fulfillment, indexing, or a named agent workflow.

Reference: https://telemio.sh/agent/sdk.md


## Runtime sessions and console deep links

Use runtime sessions when a service process, worker, agent, VM/sandbox, browser automation session, mobile app session, serverless execution, desktop client, CLI, workflow, or job has a meaningful lifecycle. Runtime sessions complement stable service/application views rather than replacing them.

Trusted services can create any runtime kind with an ingest/write credential. Browser, mobile, and desktop applications must use a client-safe ingest key and can create only distributed-client runtime kinds. Telemio returns a short-lived `tmio_rt_...` ingest token, resource attributes, and `consoleUrl` pointing to `https://console.telemio.sh/runtimes/<id>`.

When one runtime starts another, preserve the parent runtime identity and normal W3C trace context. Set `externalUrl` when the source product has its own session/runtime page so Telemio and the source application can deep-link to one another.

Reference: https://telemio.sh/agent/runtime-sessions.md

## MCP workspace companion

Use `https://mcp.telemio.sh/mcp` when a coding agent or harness should work alongside a Telemio workspace. Create the workspace-bound credential from the console MCP page. MCP keys use the `tmio_mcp_` prefix, are shown in plaintext only at creation, and cannot switch to another workspace.

The MCP surface can summarize and query workspace telemetry, inspect runtime graphs, create TQL-backed dashboards, discover actionable integration setup paths, and return direct console links. Use it before changing instrumentation and again afterward to verify the new signals.

Reference: https://telemio.sh/agent/mcp.md

## Agentic runtimes

Treat agentic runtimes as application runtimes, not a separate analytics feed. Instrument the orchestration boundary as well as individual model and tool calls.

Detect processes that invoke models/embeddings, execute tools/functions, host or call MCP, perform retrieval, schedule durable/background agent work, coordinate multiple agents or handoffs, retry model/tool steps, evaluate outcomes, or maintain conversation/run/workflow state.

A useful trace can look like:

    request / job / user action
      -> agent or workflow run
        -> model invocation
        -> retrieval
          -> datastore
        -> tool execution
          -> MCP / HTTP / RPC dependency
        -> handoff / child agent
          -> model invocation
        -> persistence / side effect

Use current OpenTelemetry GenAI semantic conventions where they fit the framework/runtime. Keep operation, model/provider, agent/workflow, tool identity/type, token usage, cost metadata, retry count, status/outcome, and stable correlation identifiers. Keep ordinary HTTP, database, messaging, and runtime spans around the agent work.

Long-running/durable agents should also retain run/workflow identity, attempt number, checkpoint/resume identity, queue/job identity, parent-child or handoff relationships, release/version, and durable step latency. If a direct parent/child trace relationship is no longer appropriate after a long resume, use propagated context when practical or span links/stable correlation identifiers.

GenAI semantic conventions evolve. Prefer current standard semantics over freezing permanent vendor-specific names when a standard already covers the operation.

Reference: https://telemio.sh/agent/agentic-runtimes.md


## Coding-agent harnesses

Use `telemio detect agents` or `telemio setup agent auto` to detect supported local coding harnesses. Runtime-specific commands are `telemio setup agent claude-code`, `codex`, `hermes`, `loki`, `gemini`, and `copilot`; Cursor, OpenCode, and Windsurf use a native-telemetry-first hook adapter path.

Claude Code, Codex, Gemini CLI, and GitHub Copilot CLI expose native OpenTelemetry surfaces. Hermes uses its lifecycle observer contract through the `hermes_otel` plugin. Loki shares one agent core across its surfaces, so instrument the core once until a native OTLP exporter exists. Keep content capture disabled by default and preserve model/tool/MCP/subagent/approval correlation.

Reference: https://telemio.sh/agent/coding-agents.md

## Agent content policy

Agent helpers are metadata-first. Useful fields include provider, model, operation, workflow or agent name, tool name/type, token counts, estimated cost, retry count, status, and stable identifiers. `telemio.agent.fingerprint(value)` can create a stable SHA-256 fingerprint when correlation is useful but exporting content is not.

For context systems, record stable context IDs, kind, version, size/token metadata, cache reuse, sensitivity classification, and fingerprints. The context body does not need to be exported for most cost, reuse, and dependency analysis.

Do not export prompt bodies, completion bodies, tool arguments/results, retrieved documents, source code, credentials, or customer content by default.

## Mobile and distributed-client credential policy

Any secret embedded in a browser or app binary should be treated as public. Do not put privileged Telemio server API keys in browser, iOS, Android, React Native, desktop, or other distributed client bundles.

Use a client-safe telemetry collection path or trusted collector/gateway. Let trusted backend services hold privileged server credentials.

## Validation

After instrumentation, run the repository's normal test, build, lint, type-check, and platform-specific commands. Report:

- runtimes found
- runtimes instrumented fully/partially/not yet
- auto/zero-code instrumentation added or reused
- manual spans/events added
- environment variables, gateways, endpoints, or client-safe configuration required
- files changed
- data intentionally excluded for privacy
- remaining instrumentation gaps

## More detailed pages

Repository setup: https://telemio.sh/agent/setup.md
OpenTelemetry: https://telemio.sh/agent/opentelemetry.md
SDK: https://telemio.sh/agent/sdk.md
Native/mobile: https://telemio.sh/agent/native-mobile.md
Java/JVM: https://telemio.sh/agent/jvm.md
Agentic runtimes: https://telemio.sh/agent/agentic-runtimes.md
Observability for agentic runtimes: https://telemio.sh/articles/observability-for-agentic-runtimes.html
OpenTelemetry for native mobile apps: https://telemio.sh/articles/native-mobile-observability-with-opentelemetry.html
OpenTelemetry for AI agents: https://telemio.sh/articles/opentelemetry-for-ai-agents.html
Node.js OpenTelemetry: https://telemio.sh/articles/instrument-nodejs-with-opentelemetry.html
Metadata-first agent observability: https://telemio.sh/articles/metadata-first-agent-observability.html
Telemio vs Honeycomb: https://telemio.sh/articles/telemio-vs-honeycomb.html
Telemio vs Datadog: https://telemio.sh/articles/telemio-vs-datadog.html
Telemio vs New Relic: https://telemio.sh/articles/telemio-vs-new-relic.html
Telemio vs Dynatrace: https://telemio.sh/articles/telemio-vs-dynatrace.html
Telemio vs Grafana: https://telemio.sh/articles/telemio-vs-grafana.html
Telemio vs Sentry: https://telemio.sh/articles/telemio-vs-sentry.html
Telemio vs Langfuse: https://telemio.sh/articles/telemio-vs-langfuse.html
Observability pricing comparison: https://telemio.sh/articles/observability-pricing-comparison.html


## Extended runtime and deployment coverage

Telemio is OTLP-first rather than SDK-per-language. Cover Node.js/TypeScript, Python, Java/JVM, .NET/C#, Go, PHP, Ruby, Rust, C/C++, Erlang/Elixir, Swift/iOS, Android/Kotlin, React Native, browser, Electron/Tauri, serverless/edge runtimes, Kubernetes, messaging systems, agentic runtimes, GPU inference servers, and profile signals through standard OpenTelemetry paths.

Use these references:
- https://telemio.sh/agent/polyglot-runtimes.md
- https://telemio.sh/agent/serverless-edge.md
- https://telemio.sh/agent/collector.md
- https://telemio.sh/agent/kubernetes.md
- https://telemio.sh/agent/messaging.md
- https://telemio.sh/agent/desktop.md
- https://telemio.sh/agent/gpu-inference.md
- https://telemio.sh/agent/profiles.md
- https://telemio.sh/agent/client-ingest.md

For agentic repositories detect OpenAI Agents SDK, LangChain/LangGraph, MCP, CrewAI, AutoGen, Semantic Kernel, Google ADK, Temporal, Inngest, Anthropic tool use, and custom model/tool loops. Reuse framework-native tracing where it already exists and avoid duplicate model/tool spans.