• otel-onboarding-style

  for general OTel taste.

• otel-python-style

  for Python services.

• otel-fastapi-style

  for FastAPI services.

• otel-livekit-style

  for LiveKit agents.

• otel-nextjs-style

  for Next.js/Vercel apps.

• otel-expo-style

  for Expo / React Native apps.

• otel-supabase-edge-style

  for Supabase Edge Functions.

• otel-generic-style

  for any other language (Go, Java/Kotlin, Ruby, Rust, .NET/C#, PHP, Elixir, plain Node, …) — use this as the fallback when none of the above match.

1. POST https://api.superlog.sh/oauth/device

   with

   Content-Type: application/json

   and body

   {"flow":"skill"}

   . Response includes

   device_code

   ,

   user_code

   ,

   verification_uri_complete

   (a

   https://superlog.sh/activate?code=…&flow=skill

   URL),

   expires_in

   (seconds),

   interval

   (poll interval seconds).
2. Open

   verification_uri_complete

   in the user's default browser (

   open

   /

   xdg-open

   /

   start ""

   ). Print the URL too so they can copy it if the open command silently fails. Tell the user briefly what's happening: signup is open in their browser, the key flows back here automatically, you're going to keep working.
3. While the user signs up, do not block. Keep going with Steps 1–4. Inline the literal sentinel

   SUPERLOG_TEST

   in the bootstrap source as a placeholder — Superlog's ingest accepts it from anyone (returns 200 without forwarding anywhere), so the user's app can boot and exercise the OTel bootstrap path while signup is in flight.
4. At Step 5, poll

   POST https://api.superlog.sh/oauth/token

   with

   {"device_code":"…"}

   every

   interval

   seconds.

   428

   =

   authorization_pending

   , keep waiting.

   200

   returns

   {ingest_key, project_id, user, org, flow:"skill"}

   .

   410

   = expired.
5. On 200: walk the source files you wrote and replace the

   SUPERLOG_TEST

   literal with the real

   ingest_key

   . Never print the key back to chat (transcripts get logged). The web

   /activate

   page already confirms hand-off to the user.
6. On 410 / user closed the tab: leave

   SUPERLOG_TEST

   in place and tell the user to sign up at https://superlog.sh/ and swap it later.

@opentelemetry/sdk-node

@vercel/otel

@opentelemetry/sdk-trace-web

opentelemetry-instrumentation-*

opentelemetry-sdk

go.opentelemetry.io/otel

sendSuperlogSpan

recordCounter

recordLog

startTelemetrySpan

withTelemetry

@superlog/otel-helpers

withSpan

@superlog/otel-helpers

package.json

startActiveSpan

try

catch

finally

tracer.startActiveSpan

span.setAttributes

SpanStatusCode

meter.createCounter

histogram.record

trace_id

span_id

LoggerProvider

LoggerProvider

OTLPLogExporter

LoggingHandler

LoggingInstrumentor

@opentelemetry/sdk-logs

pino

winston

bunyan

@vercel/otel

logRecordProcessor(s)

• Handler attached to a named logger when the app uses the root logger (or vice versa) — nothing flows.
• Default level filter (e.g. WARNING) swallowing the INFO/DEBUG lines the user actually wants in Superlog.

• BatchLogRecordProcessor

  not flushed on shutdown → short-lived CLIs, serverless, and edge functions drop the last batch. Wire

  shutdown()

  /

  forceFlush()

  into the runtime's exit hook.
• An existing vendor transport (Pino → Logtail, Winston → Datadog, etc.) left in place is fine and expected — but make sure you're bridging from the logger, not adding a second transport that double-emits the same line through a different formatter.
• Logs emitted outside any span will arrive without

  trace_id

  /

  span_id

  . That is correct and expected; do not "fix" it by starting throwaway spans around log calls.

• The bootstrap file must run before any framework imports. Use the language/framework's documented hook (

  --import

  flag,

  instrumentation.ts

  , top-of-

  main.py

  import, etc.).
• Inline the endpoint (

  https://intake.superlog.sh

  ) and the project's ingest key directly in the bootstrap source. Don't read from

  process.env.OTEL_EXPORTER_OTLP_*

  or write any

  .env

  files — the key is write-only, and inline configuration removes a whole class of "OTel didn't start because env vars weren't set" deploy failures. (See the framework-specific style skills for the exact shape per stack.)
• Use HTTP OTLP exporters, not gRPC. gRPC pulls in native bindings that break bundlers and complicate containers.
• Use the project's existing package manager (detect via lockfile).
• Prefer idempotent edits. If a config file already exists, edit don't overwrite.
• Set resource attributes on the OTel resource for every service:

  service.name

  ,

  service.version

  ,

  deployment.environment.name

  , and

  vcs.repository.url.full

  — the canonical https URL of the repo (e.g.

  https://github.com/acme/api

  ). The repo URL is the important one and is fine to hardcode alongside

  service.name

  in the SDK init; if the build platform exposes the slug (Vercel

  VERCEL_GIT_REPO_OWNER

  /

  VERCEL_GIT_REPO_SLUG

  , Railway

  RAILWAY_GIT_REPO_OWNER

  /

  RAILWAY_GIT_REPO_NAME

  ), prefer reading from env. Also set

  vcs.ref.head.revision

  (commit SHA) on a best-effort basis from whatever env the runtime already injects (

  VERCEL_GIT_COMMIT_SHA

  ,

  RAILWAY_GIT_COMMIT_SHA

  ,

  GITHUB_SHA

  ,

  SOURCE_COMMIT

  ,

  GIT_COMMIT

  ,

  HEROKU_SLUG_COMMIT

  , …). Do not shell out to

  git

  from the running process. Skipping the SHA is fine, skipping the URL is not. Use the OTel semantic-convention keys exactly — do not invent

  git.repo

  /

  app.repo_url

  .

• Next.js/Vercel: use

  instrumentation.ts

  with

  @vercel/otel

  registerOTel(...)

  as the bootstrap. Do not substitute a raw

  @opentelemetry/sdk-node

  /

  NodeSDK

  bootstrap unless the repo already uses that architecture and you are extending it. Use

  @opentelemetry/api

  tracers/meters inside route handlers only where auto-instrumentation is blind.

  registerOTel

  does not export logs by default — pass

  logRecordProcessor

  (v1) /

  logRecordProcessors

  (v2) with an

  OTLPLogExporter

  from

  @opentelemetry/exporter-logs-otlp-http

  , or no logs will leave the process. Match the option name to the installed

  @vercel/otel

  major version.
• Expo/React Native: preserve existing Expo Go / unsupported-runtime guards. In supported builds, call

  initObservability()

  before Sentry and before app registration/user code. Inline the endpoint + ingest key in the observability module — no

  EXPO_PUBLIC_OTEL_*

  env vars. The bootstrap reads them straight from constants.
• Supabase Edge Functions: native Deno OpenTelemetry does not work in hosted Supabase Edge today. Use the tiny OTel-shaped shim pattern above; keep exporter endpoint/headers in one setup area and avoid Superlog-specific function/file names.
• Python/FastAPI: use native instrumentation such as

  FastAPIInstrumentor.instrument_app(app)

  rather than replacing request handling with manual middleware.
• Python/LiveKit: lifecycle spans that cross shutdown callbacks may use

  start_span

  +

  trace.use_span(..., end_on_exit=False)

  and end in the shutdown callback. Bounded work should still use decorators or context managers.

• Naming:

  domain.verb

  (

  order.process

  ,

  payment.charge

  ,

  email.send

  ,

  agent.run

  ,

  interview.create

  ,

  job.<type>

  ).
• Attributes: entity IDs (order.id, user.id, workspace.id, tenant.id), counts, key boolean branch outcomes, model name / provider for LLM calls.
• Record exceptions:

  span.recordException(err)

  +

  span.setStatus({ code: ERROR })

  on failure paths.
• For Python functions with clear boundaries, prefer

  @tracer.start_as_current_span("operation.name")

  — the same call works as a decorator and as a context manager, and the decorator form is usually what you want for a whole function:
  python

  @tracer.start_as_current_span("do_work")
  def do_work():
      print("doing some work...")

  Use a context manager when a decorator does not fit (partial scope, dynamic span name, etc.). Do not use detached

  start_span()

  + manual

  end()

  for bounded work.
• Skip trivial getters, pure transforms, internal helpers — anything with no real latency or failure mode.
• Never put PII in attributes (emails, passwords, tokens, full request bodies).

• Business logic counters. Every meaningful state transition: created, started, completed, failed, retried. Per-tenant, per-channel, per-status — low-cardinality dimensions only (never user/order IDs).
• Performance histograms. Latency of operations the user cares about, queue depth, batch sizes, payload sizes. Reuse existing timing instrumentation if the project already has any (

  time.perf_counter

  blocks, custom

  LatencyTracker

  s, "[TIMING]" log lines) — emit a histogram from those measurements rather than measuring twice.
• Costs — especially LLM costs. If the project calls OpenAI / Anthropic / Google / any LLM provider, prefer provider instrumentation such as OpenInference where available so native SDK calls stay readable. Do not add pricing constants or LLM cost math in product handlers; Superlog computes estimated cost centrally in the UI/query layer from captured provider/model/token attributes. Avoid duplicating token counters already captured by provider instrumentation.

1. Run the project's own dev or build command (whatever its

   package.json

   /

   pyproject

   /

   Makefile

   already wires up). Confirm it starts cleanly with no errors that trace back to your OTel install. Also run a telemetry bootstrap smoke that imports or starts the app, so provider setup, exporter construction, log bridging, and framework instrumentation all initialize. For a Python server this can be an import/startup command such as

   uv run python -c 'from app.main import app; print(app.title)'

   ; for Node/Next use the repo's build/start path. For a server, hit at least one route with curl so traffic flows through the instrumentation; choose a route that exercises an instrumented operation when practical, not only a static health route. For a CLI, invoke a real command. Don't ship if the app's own startup is now broken — that's a regression.
2. Confirm telemetry leaves the process — for all three signals. With the inline

   SUPERLOG_TEST

   (or real key) in the bootstrap, OTLP POSTs from the dev server should return 2xx for each of

   /v1/traces

   ,

   /v1/logs

   , and

   /v1/metrics

   — that proves the full bootstrap is reaching the network, not just the trace pipeline. The signal is the running app's own POSTs to all three paths succeeding by the time the dev server shuts down. To force the logs path specifically, hit a route (or invoke a CLI command) that you know calls the project's logger inside an instrumented operation, then watch the dev server's outbound traffic / debug exporter output for a

   /v1/logs

   POST. If only

   /v1/traces

   shows up, the log bridge isn't wired (most common causes:

   LoggerProvider

   never set, handler attached to the wrong logger, level filter too strict,

   @vercel/otel

   missing

   logRecordProcessor(s)

   , or shutdown not flushing the batch processor).

POST https://api.superlog.sh/oauth/token

{"device_code":"…"}

interval

expires_in

• On 200: walk every source file where you inlined

  SUPERLOG_TEST

  and replace it with the real

  ingest_key

  . Never print the key back to chat (transcripts get logged); the web

  /activate

  page already confirms hand-off to the user.
• On 410 / poll timeout: leave

  SUPERLOG_TEST

  inline, tell the user "sign-up didn't finish in time — sign up at https://superlog.sh/ when you're ready and swap the literal in the bootstrap files I wrote." Continue with the rest of the closing message.

"Opening the GitHub install page — pick the repos you want Superlog to read and approve. Press enter when you're back."

https://api.superlog.sh/github/install?user_code=<USER_CODE>

open

xdg-open

start ""

/activate?…&gh=done

"Opening Slack OAuth — pick the workspace and approve. Press enter when you're back."

https://api.superlog.sh/slack/install?user_code=<USER_CODE>

/activate?…&slack=done

claude mcp add --transport http superlog https://api.superlog.sh/mcp

• Codex:

  codex mcp add superlog --url https://api.superlog.sh/mcp && codex mcp login superlog

• Cursor / others: copy the

  mcpServers

  snippet from https://superlog.sh/ → Connect.

• Never modify files outside the project root.
• Never commit, push, or open PRs.
• Inline the ingest key in source. It's a project-scoped, write-only token (think Sentry DSN); env-var indirection just adds deploy-time failure modes for no gain.
• Never remove an existing observability vendor unless the user asks for it.
• Use the project's existing package manager and existing logger.
• Prefer native OTel packages for the language; don't reinvent telemetry plumbing the SDK already provides.
• If the dev/build command errors out because of your instrumentation, that's a failure — fix it or report it, don't paper over it.