Instrument Your First Service

Complete workflow to choose an SDK, configure auth, attach environment context, and validate production telemetry.

Instrument Your First Service

Use this workflow when you want one service fully instrumented and operationally useful, not just sending raw events.

Goal

By the end of this flow, one production-relevant service should emit telemetry with stable identity, deployment context, and enough evidence for incident diagnosis.

Step 1: Pick the service correctly

Choose the service with the highest operational risk, not the easiest local demo.

Good first targets:

  • Checkout
  • Auth
  • Billing
  • API gateway

Step 2: Pick the SDK

Use SDK Catalog, then open the language-specific page:

Step 3: Configure authentication

Read Authentication and ensure environment-specific credentials.

Minimum required values:

  • OBTRACE_API_KEY
  • OBTRACE_TENANT_ID
  • OBTRACE_PROJECT_ID

Step 4: Add canonical runtime attributes

Every event should contain:

  • service
  • env
  • version
  • region when relevant

Without these fields, incident grouping and release correlation get weaker fast.

Examples with the active SDKs:

client = ObtraceClient(
    ObtraceConfig(
        api_key=os.getenv("OBTRACE_API_KEY"),
        tenant_id=os.getenv("OBTRACE_TENANT_ID"),
        project_id=os.getenv("OBTRACE_PROJECT_ID"),
        app_id="checkout-api",
        service_name="checkout-api",
        service_version=os.getenv("OBTRACE_SERVICE_VERSION", "2026.03.10"),
        env=os.getenv("OBTRACE_ENV", "prod"),
    )
)
 
client.span("checkout.charge", attrs={"cloud.region": os.getenv("AWS_REGION", "us-east-1")})
client := ob.NewClient(ob.Config{
  APIKey: os.Getenv("OBTRACE_API_KEY"),
  TenantID: os.Getenv("OBTRACE_TENANT_ID"),
  ProjectID: os.Getenv("OBTRACE_PROJECT_ID"),
  AppID: "checkout-api",
  Env: os.Getenv("OBTRACE_ENV"),
  ServiceName: "checkout-api",
  ServiceVersion: os.Getenv("OBTRACE_SERVICE_VERSION"),
})
 
client.Span("checkout.charge", "", "", 0, "", map[string]any{
  "cloud.region": os.Getenv("AWS_REGION"),
})
ObtraceConfig cfg = new ObtraceConfig();
cfg.apiKey = System.getenv("OBTRACE_API_KEY");
cfg.tenantId = System.getenv("OBTRACE_TENANT_ID");
cfg.projectId = System.getenv("OBTRACE_PROJECT_ID");
cfg.appId = "checkout-api";
cfg.serviceName = "checkout-api";
cfg.serviceVersion = System.getenv().getOrDefault("OBTRACE_SERVICE_VERSION", "2026.03.10");
cfg.env = System.getenv().getOrDefault("OBTRACE_ENV", "prod");

What the core ingest expects:

  • tenant_id
  • project_id
  • app_id
  • service_name
  • env
  • service_version

The SDKs map those fields into OTLP. Ingest then derives the scoped envelope used by storage and incident projection.

Step 5: Attach the runtime environment

Choose the runtime path that matches production:

Step 6: Validate before rollout expands

Expected result:

  • Continuous telemetry
  • No 401/403 auth failures
  • Stable tags across restarts and deploys
  • At least one trace or error with enough context for diagnosis

Minimum validation path:

  1. Hit one real request path in production or staging.
  2. Confirm one log and one trace arrive with the same service, env, and version.
  3. Confirm region is present if the service is multi-region.
  4. Only then expand rollout.

Step 7: Add release context

Before scaling rollout, connect CI/CD metadata so incidents can be tied to deploys.

Read:

Done definition

This workflow is complete only when:

  • One service is instrumented in production
  • The service can be filtered cleanly by service, env, and version
  • Incident evidence is usable without manual log archaeology

On this page