Generic OTel Style

Use this skill for any language that does not have its own otel-*-style
companion (Go, Java/Kotlin, Ruby, Rust, .NET/C#, PHP, Elixir, plain
Node/TypeScript without Next.js or Expo, etc.). Read otel-onboarding-style
first for the cross-language rules; this skill is the language-agnostic
translation of that guidance.

If a language-specific skill exists for the runtime in front of you
(otel-python-style, otel-fastapi-style, otel-livekit-style,
otel-nextjs-style, otel-expo-style, otel-supabase-edge-style), prefer
that one — it overrides this skill.

Use the language's official OTel SDK

Pull the SDK and exporters from the OpenTelemetry project for that language.
Do not invent helper APIs around it. Examples:

• Go: go.opentelemetry.io/otel, otel/sdk, otel/exporters/otlp/otlptrace/otlptracehttp
• Java/Kotlin: io.opentelemetry:opentelemetry-sdk + opentelemetry-exporter-otlp (or the Java agent for auto-instrumentation)
• Ruby: opentelemetry-sdk, opentelemetry-exporter-otlp, opentelemetry-instrumentation-all
• Rust: opentelemetry, opentelemetry_sdk, opentelemetry-otlp
• .NET/C#: OpenTelemetry, OpenTelemetry.Exporter.OpenTelemetryProtocol, framework OpenTelemetry.Instrumentation.* packages
• PHP: open-telemetry/sdk, open-telemetry/exporter-otlp
• Elixir: :opentelemetry, :opentelemetry_api, :opentelemetry_exporter
• Plain Node/TS: @opentelemetry/sdk-node + @opentelemetry/auto-instrumentations-node (use @vercel/otel for Next.js — see otel-nextjs-style)

Use HTTP OTLP exporters, not gRPC. gRPC pulls in native bindings that break
bundlers, slim containers, and serverless cold starts.

Acquire tracers/meters once, at module/package scope

Whatever the idiomatic "module top" is in that language — package-level vars
in Go, static fields in Java/.NET, top-of-file constants in Ruby/Node,
@moduledoc-level attributes in Elixir. Don't construct a fresh tracer or
meter on every call.

// Go
var (
    tracer = otel.Tracer("mugline.api")
    meter  = otel.Meter("mugline.api")
    ordersSubmitted, _ = meter.Int64Counter("orders.submitted")
)

// Java
private static final Tracer TRACER = GlobalOpenTelemetry.getTracer("mugline.api");
private static final Meter METER = GlobalOpenTelemetry.getMeter("mugline.api");
private static final LongCounter ORDERS_SUBMITTED =
    METER.counterBuilder("orders.submitted").build();

Bounded work

For any function with clear start/end boundaries, open a span that covers the
whole operation and ends automatically. Use the language's built-in
construct — defer span.End(), try-with-resources, using, with, block
form, etc. Do not start a span in one place and end it manually somewhere
else for bounded work.

ctx, span := tracer.Start(ctx, "order.submit")
defer span.End()
span.SetAttributes(
    attribute.String("tenant.id", tenantID),
    attribute.String("order.id", orderID),
)

using var activity = ActivitySource.StartActivity("order.submit");
activity?.SetTag("tenant.id", tenantId);
activity?.SetTag("order.id", orderId);

Span names are conventional and low-cardinality: domain.verb
(order.submit, payment.charge, voice.session, llm.generate_copy).

Error paths

Record the exception and set the span status to error on the active span,
then re-raise so the caller still sees the failure.

if err != nil {
    span.RecordError(err)
    span.SetStatus(codes.Error, err.Error())
    return err
}

rescue => e
  span = OpenTelemetry::Trace.current_span
  span.record_exception(e)
  span.status = OpenTelemetry::Trace::Status.error(e.message)
  raise
end

Logs

If logs are claimed as OTLP-forwarded, install the OTel log bridge for that
language so existing log calls carry trace_id / span_id automatically.
Keep the existing logger (log/slog, Logback, Logger, Serilog,
Logger.Logger, etc.) — just add an OTLP handler/processor underneath.

Do not replace the project's structured logger with a bespoke one.

Init behavior

Use the source-level public Superlog configuration pattern from
otel-onboarding-style in the telemetry init area. The public project token is
write-only and belongs with the endpoint in one setup block, like a PostHog
project token or Sentry DSN.

If init can run more than once (test reloads, framework restarts, multiple
entrypoints), guard provider/exporter setup so duplicate processors aren't
installed.

Resource attributes

Set on the OTel resource for every service:

• service.name
• service.version (when available)
• deployment.environment.name
• vcs.repository.url.full — canonical https URL of the repo
• vcs.ref.head.revision — best-effort commit SHA from build env
  (GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, RAILWAY_GIT_COMMIT_SHA,
  SOURCE_COMMIT, GIT_COMMIT, HEROKU_SLUG_COMMIT, …)

Do not shell out to git from the running process. Use the OTel
semantic-convention keys exactly — do not invent git.repo / app.repo_url.

Metrics

Counters for additive totals: requests, events, jobs, errors, business
state transitions. Histograms for distributions: duration, latency, payload
size, queue depth.

Low-cardinality attributes only — tenant/org/project, operation/use case,
provider/model, outcome. Do not put raw user IDs or request IDs in metric
tags.

For LLM token/cost telemetry, follow the gen_ai.* / app.gen_ai.*
convention from otel-onboarding-style. Do not add app-side llm.cost_usd
metrics — Superlog computes cost centrally.

When no OTel SDK exists

Some runtimes have no usable OpenTelemetry SDK — older languages (Perl,
Bash/shell, Lua, Crystal, Nim, Zig), niche runtimes, restricted edge
environments, or languages whose "SDK" is abandoned/pre-alpha and would be
worse than rolling your own. In that case, emit OTLP/HTTP JSON directly.
The wire format is stable, documented, and small.

Rules for a hand-rolled OTLP emitter:

• Speak OTLP/HTTP+JSON, not a vendor format. POST to
  https://intake.superlog.sh/v1/traces, /v1/metrics, /v1/logs with
  Content-Type: application/json and the public project token in the
  x-api-key header (x-api-key: sl_public_...). Ingest reads only
  x-api-key or Authorization: Bearer <token> (literal Bearer prefix) —
  any other header name 401s on every request even when the token is valid. Body
  shape follows the OTLP proto-to-JSON
  mapping (resourceSpans / resourceMetrics / resourceLogs →
  scopeSpans → spans, with traceId/spanId as lowercase hex).
• Keep the shim tiny and OTel-shaped. Expose names a future SDK port
  could drop into: startSpan(name), setAttributes, recordException,
  endSpan, counter.add, histogram.record. Don't invent
  sendSuperlogEvent or recordCounter — those are exactly what the style
  forbids elsewhere.
• Generate IDs correctly. 16-byte trace IDs and 8-byte span IDs as
  lowercase hex; use the runtime's CSPRNG. Timestamps are nanoseconds since
  Unix epoch (time.UnixNano() equivalent — beware language defaults that
  give ms or µs).
• Batch and flush. Buffer spans/metrics/logs in memory, flush on a small
  interval (a few seconds) and on process exit. Drop on overflow rather
  than blocking the hot path. For a CLI or short-lived script, do a final
  synchronous flush before exit.
• Resource attributes still apply. Set service.name,
  service.version, deployment.environment.name,
  vcs.repository.url.full, vcs.ref.head.revision once on the resource
  and reuse it on every export envelope.
• Use the same public config as SDK-based services. Keep the endpoint and
  public project token in one setup block, and set resource attributes on every export
  envelope. If signup is still in progress, initialize cleanly and note that
  ingest may reject the generated token until the browser flow claims it.
• Trace context propagation uses W3C traceparent. Read it from
  inbound HTTP headers if the runtime is a server; emit it on outbound
  requests as traceparent: 00-<trace-id>-<span-id>-01.

For shell scripts and one-shot tools, even a single curl POST to
/v1/traces with a hand-built JSON body is acceptable — that's still
OTLP, and it composes with everything else in the user's pipeline.

If the language does have an SDK but it doesn't load in this particular
runtime (bundler, edge, restricted FFI), the same shim approach applies.
The Supabase Edge skill is one worked example.

Auto-instrumentation

Where the language has a packaged auto-instrumentation story, use it as the
floor:

• Java: the OpenTelemetry Java agent (-javaagent:opentelemetry-javaagent.jar)
• .NET: OpenTelemetry.Instrumentation.AspNetCore / Http / SqlClient etc.
• Ruby: opentelemetry-instrumentation-all
• Node: @opentelemetry/auto-instrumentations-node
• Go: framework-specific otelhttp, otelgin, otelpgx, otelsql wrappers (Go has no global agent)
• PHP: the open-telemetry/opentelemetry-auto-* extensions
• Elixir: :opentelemetry_phoenix, :opentelemetry_ecto, :opentelemetry_cowboy

Then add custom spans, metrics, and logs around business operations the
auto-instrumentation can't see — the operations a human operator would
actually want to inspect when something looks wrong.