@telemio/sdk

First-party Telemio SDK for manual telemetry, agent observability, context efficiency, feature flags, and experiments.

Use standard OpenTelemetry auto-instrumentation whenever it fits your runtime. @telemio/sdk is the lightweight manual surface for the places where you need explicit spans, logs, metrics, product events, agent telemetry, or Telemio feature controls.

Install

npm i @telemio/sdk

Requires Node.js 20+ for server runtimes. Browser and edge runtimes need Fetch and Web Crypto APIs.

Quick start

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

The default endpoint is https://api.telemio.sh. Self-hosted or custom deployments can pass endpoint explicitly.

Traces

const span = telemio.tracer.startSpan("order.fulfill", {
  "order.id": order.id
})

try {
  await fulfillOrder(order)
  span.setStatus("ok")
} catch (error) {
  span.recordException(error)
  throw error
} finally {
  await span.end()
}

Logs and metrics

await telemio.logger.info("checkout completed", {
  "checkout.provider": "stripe"
})

await telemio.metrics.count("checkout.completed", 1)
await telemio.metrics.timing("checkout.duration", 184)

Product and custom events

await telemio.track("subscription.upgraded", {
  plan: "pro",
  seats: 12
})

Agent telemetry

Agent helpers are metadata-only by default. Prompt and completion bodies are not automatically captured.

const run = telemio.agent.startAgent("support-agent", {
  "gen_ai.provider.name": "openai",
  "gen_ai.request.model": "gpt-5"
})

const tool = telemio.agent.startTool("lookup_customer", {
  "gen_ai.tool.type": "datastore"
}, run)

await tool.end()

await telemio.agent.recordUsage({
  agentName: "support-agent",
  provider: "openai",
  model: "gpt-5",
  inputTokens: 820,
  outputTokens: 142,
  estimatedCostUsd: 0.01
})

run.setStatus("ok")
await run.end()

Use telemio.agent.fingerprint(value) when you need a stable content fingerprint without exporting the content itself.

Context efficiency

await telemio.context.loaded({
  id: "ctx:architecture",
  kind: "documentation",
  version: process.env.GIT_COMMIT,
  estimatedTokens: 4200,
  sensitivity: "internal"
})

await telemio.context.reused({
  id: "ctx:architecture",
  kind: "documentation",
  estimatedTokens: 4200,
  cacheReadTokens: 3900,
  sensitivity: "internal"
})

Context helpers send identifiers, fingerprints, size/token metadata, and attributes. They do not send the context body.

Feature flags and experiments

const checkout = await telemio.flags.boolean("checkout-v2", false, {
  targetingKey: user.id,
  plan: user.plan,
  country: user.country
})

if (checkout.value) {
  renderCheckoutV2()
}

await telemio.experiments.track("checkout.completed", {
  targetingKey: user.id
}, {
  value: order.total
})

telemio.flags.details() returns the resolved value, variant, reason, ruleset version, and experiment ID when available. Typed helpers are available for boolean, string, number, and JSON values.

The package also exports createTelemioOpenFeatureProvider() for applications using OpenFeature-compatible server SDKs.

Custom fetch implementation

Edge workers, tests, proxies, and custom runtimes can provide their own Fetch implementation.

const telemio = createTelemio({
  serviceName: "worker",
  apiKey: env.TELEMIO_API_KEY,
  fetch: (input, init) => env.TELEMETRY_PROXY.fetch(input, init)
})

Security

Do not put server API keys in browser bundles. Use Telemio browser/RUM setup for client-side telemetry and keep privileged keys on trusted server runtimes.

Avoid placing credentials, authorization headers, payment data, or sensitive user content in telemetry attributes. Agent and context helpers are designed to work with metadata rather than raw prompt, completion, repository, or tool-result bodies.

License

Apache-2.0.

Runtime sessions and console deep links

Use runtime sessions when an application has a meaningful lifecycle that should be navigable in the Telemio console: a backend process/deploy, worker, agent session, VM, browser automation session, mobile session, serverless job, desktop session, workflow, or CLI run.

import { createTelemio } from "@telemio/sdk"

const telemio = createTelemio({
  apiKey: process.env.TELEMIO_API_KEY,
  workspaceId: process.env.TELEMIO_WORKSPACE_ID,
  serviceName: "checkout-worker"
})

const runtime = await telemio.runtime.start({
  kind: "worker",
  provider: "my-worker-platform",
  externalId: process.env.JOB_ID,
  externalUrl: process.env.JOB_URL,
  expiresInSeconds: 3600
})

console.log(runtime.consoleUrl)

const runtimeTelemio = createTelemio(runtime.clientOptions)
await runtimeTelemio.metrics.count("jobs.started")

await runtime.end({ outcome: "completed" })

A child runtime can inherit the parent session without sharing a permanent workspace credential:

const browser = await runtime.startChild({
  kind: "browser",
  provider: "guardian",
  externalId: guardianSessionId
})

The returned runtime includes a short-lived tmio_rt_* ingest token and a stable consoleUrl. Treat the runtime token as a secret while it is valid, but prefer it over distributing a permanent workspace API key.

For browser, mobile, and distributed desktop applications, create the outer runtime with a client-safe ingest key rather than a privileged server API key. The browser/mobile client key can only create browser/mobile/desktop runtime kinds and remains subject to its origin/app bindings and budgets.