Instrumente Seu Primeiro Serviço

Use este fluxo quando você quiser um serviço realmente instrumentado e operacionalmente útil, não apenas enviando eventos crus.

Objetivo

Ao final, um serviço relevante em produção deve emitir telemetria com identidade estável, contexto de deploy e evidência suficiente para diagnóstico de incidentes.

Passo 1: Escolha o serviço certo

Comece pelo serviço de maior risco operacional, não pelo demo mais fácil.

Passo 2: Escolha o SDK

Use o Catálogo de SDKs e depois abra a página da linguagem:

• Python
• Go
• Java
• Node/Bun
• .NET

Passo 3: Configure autenticação

Leia Autenticação e use credenciais separadas por ambiente.

Passo 4: Adicione atributos canônicos

Todo evento deve conter:

• service
• env
• version
• region quando relevante

Exemplos reais:

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

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

O core do ingest espera:

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

Passo 5: Conecte o ambiente de runtime

• Kubernetes
• Serverless
• Guias específicos em /pt-BR/docs/integrations/*

Passo 6: Valide antes de expandir

Resultado esperado:

• Telemetria continua
• Sem erros 401/403
• Tags estáveis entre restarts e deploys
• Pelo menos um trace ou erro com contexto suficiente

Validação mínima:

1. Rode um request real.
2. Confira um log e um trace com o mesmo service, env e version.
3. Confira region se o serviço for multi-região.

Passo 7: Anexe contexto de release

Antes de escalar rollout, conecte metadata de CI/CD para amarrar incidentes a deploys.

Definição de pronto

• Um serviço em produção instrumentado
• Filtro limpo por service, env e version
• Evidência suficiente para diagnóstico sem arqueologia manual