{"meta":{"title":"Instrumentação OpenTelemetry para o Copilot SDK","intro":"Este guia mostra como adicionar o rastreamento OpenTelemetry aos aplicativos SDK do Copilot.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/copilot/how-tos/copilot-sdk/observability","title":"Observability"},{"href":"/pt/copilot/how-tos/copilot-sdk/observability/opentelemetry","title":"Opentelemetry"}],"documentType":"article"},"body":"# Instrumentação OpenTelemetry para o Copilot SDK\n\nEste guia mostra como adicionar o rastreamento OpenTelemetry aos aplicativos SDK do Copilot.\n\n\n\n\n\n## Suporte interno à telemetria\n\nO SDK tem suporte interno para configurar o OpenTelemetry no processo da CLI e propagar o Contexto de Rastreamento W3C entre o SDK e a CLI. Forneça um `TelemetryConfig` ao criar o cliente para aderir:\n\n
\n
TypeScript
\n\n\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient({\n telemetry: {\n otlpEndpoint: \"http://localhost:4318\",\n },\n});\n```\n\n
\n\n
Python
\n\n\n\n```python\nfrom copilot import CopilotClient\n\nclient = CopilotClient(\n telemetry={\n \"otlp_endpoint\": \"http://localhost:4318\",\n },\n)\n```\n\n
\n\n
Go
\n\n\n\n```golang\nclient := copilot.NewClient(&copilot.ClientOptions{\n Telemetry: &copilot.TelemetryConfig{\n OTLPEndpoint: \"http://localhost:4318\",\n },\n})\n```\n\n
\n\n
.NET
\n\n\n\n```csharp\nvar client = new CopilotClient(new CopilotClientOptions\n{\n Telemetry = new TelemetryConfig\n {\n OtlpEndpoint = \"http://localhost:4318\",\n },\n});\n```\n\n
\n\n
Java
\n\n\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\nvar client = new CopilotClient(new CopilotClientOptions()\n .setTelemetry(new TelemetryConfig()\n .setOtlpEndpoint(\"http://localhost:4318\"))\n);\n```\n\n
\n\n
Rust
\n\n\n\n```rust\nuse github_copilot_sdk::{Client, ClientOptions, TelemetryConfig};\n\nlet client = Client::start(ClientOptions::new()\n .with_telemetry(TelemetryConfig::new()\n .with_otlp_endpoint(\"http://localhost:4318\"))\n).await?;\n```\n\n
\n\n
\n\n### Opções de TelemetryConfig\n\n| Opção | Node.js | Python | Go | .NET | Java | Rust | Descrição |\n| ------------------------- | ---------------- | ----------------- | ---------------- | ---------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------- |\n| Ponto de extremidade OTLP | `otlpEndpoint` | `otlp_endpoint` | `OTLPEndpoint` | `OtlpEndpoint` | `otlpEndpoint` | `otlp_endpoint` | URL do ponto de extremidade OTLP HTTP |\n| Protocolo OTLP | `otlpProtocol` | `otlp_protocol` | `OTLPProtocol` | `OtlpProtocol` | `otlpProtocol` | `otlp_protocol` | Protocolo HTTP OTLP para todos os sinais: `\"http/json\"` ou `\"http/protobuf\"` |\n| Caminho do arquivo | `filePath` | `file_path` | `FilePath` | `FilePath` | `filePath` | `file_path` | Caminho do arquivo para saída de rastreamento de linhas JSON |\n| Tipo de exportador | `exporterType` | `exporter_type` | `ExporterType` | `ExporterType` | `exporterType` | `exporter_type` | |\n| `\"otlp-http\"` ou `\"file\"` | | | | | | | |\n| Nome de origem | `sourceName` | `source_name` | `SourceName` | `SourceName` | `sourceName` | `source_name` | Nome do escopo da instrumentação |\n| Capturar conteúdo | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | `captureContent` | `capture_content` | Se o conteúdo da mensagem deve ser capturado |\n\nO campo de protocolo OTLP configura o exportador `\"otlp-http\"` da CLI para todos os sinais. Deixe-o não definido para usar o padrão da CLI ou defina-o como `\"http/protobuf\"` para exportar protobuf por HTTP.\n\n### Propagação de contexto de traceamento\n\n> **A maioria dos usuários não precisa disso.** O `TelemetryConfig` acima é tudo o que você precisa para coletar os rastros da CLI. A propagação de contexto de rastreamento descrita nesta seção é um **recurso avançado** para os aplicativos que criam os seus próprios intervalos OpenTelemetry e querem que eles apareçam no **mesmo rastreamento distribuído** que os intervalos da CLI.\n\nO SDK pode propagar o Contexto de Rastreamento W3C (`traceparent`/`tracestate`) em conteúdos JSON-RPC para que os intervalos do aplicativo e os intervalos da CLI estejam vinculados em um rastreamento distribuído. Isso é útil quando, por exemplo, você quer visualizar um span de \"tratamento da chamada de ferramenta\" no seu aplicativo, aninhado dentro do span \"executar ferramenta\" da CLI, ou mostrar a chamada do SDK como filha do seu span de tratamento da solicitação.\n\nPara atribuição de custo junto com rastreamentos, assine os eventos `assistant.usage` e inspecione `apiEndpoint` (`AssistantUsageApiEndpoint`) para visualizar se uma interação usou Conclusões de Chat, Respostas ou Mensagens do Anthropic; consulte [Eventos de sessão de streaming](/pt/copilot/how-tos/copilot-sdk/features/streaming-events).\n\n#### SDK → CLI (de saída)\n\nPara **Node.js**, forneça uma função de `onGetTraceContext` callback nas opções do cliente. Isso só será necessário se o aplicativo já usar `@opentelemetry/api` e você quiser vincular seus intervalos com os intervalos da CLI. O SDK chama esse retorno de chamada antes de `session.create`, `session.resume` e `session.send` RPCs.\n\n\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\nimport { propagation, context } from \"@opentelemetry/api\";\n\nconst client = new CopilotClient({\n telemetry: { otlpEndpoint: \"http://localhost:4318\" },\n onGetTraceContext: () => {\n const carrier: Record = {};\n propagation.inject(context.active(), carrier);\n return carrier; // { traceparent: \"00-...\", tracestate: \"...\" }\n },\n});\n```\n\nPara **Python**, **Go** e **.NET**, a injeção de contexto de rastreamento é automática quando a respectiva API OpenTelemetry/Activity está configurada— nenhum retorno de chamada é necessário.\n\n#### CLI → SDK (de entrada)\n\nQuando a CLI chama um manipulador de ferramenta, o `traceparent` e `tracestate` do span da CLI está disponível em todos os idiomas:\n\n* ```\n **Vá para**: o campo `ToolInvocation.TraceContext` é um `context.Context` com o rastreamento já restaurado, use-o diretamente como pai dos seus spans.\n ```\n* ```\n **Python**: o contexto de rastreamento é restaurado automaticamente no manipulador por meio de `trace_context()`, os spans filho têm automaticamente como pai o span da CLI.\n ```\n* ```\n **.NET**: o contexto de rastreamento é restaurado automaticamente via: `RestoreTraceContext()`instâncias filhas de `Activity` são associadas automaticamente como filhas ao span da CLI.\n ```\n* **Node.js**: Como o SDK não tem dependência do OpenTelemetry, `traceparent` e `tracestate` são passados como strings brutas no objeto `ToolInvocation`. Restaure o contexto manualmente, se necessário:\n\n\n\n```typescript\nimport { defineTool } from \"@github/copilot-sdk\";\nimport { propagation, context, trace } from \"@opentelemetry/api\";\n\nconst myTool = defineTool(\"my-tool\", {\n description: \"Do work\",\n handler: async (args, invocation) => {\n // Restore the CLI's trace context as the active context\n const carrier = {\n traceparent: invocation.traceparent,\n tracestate: invocation.tracestate,\n };\n const parentCtx = propagation.extract(context.active(), carrier);\n\n // Create a child span under the CLI's span\n const tracer = trace.getTracer(\"my-app\");\n return context.with(parentCtx, () =>\n tracer.startActiveSpan(\"my-tool\", async (span) => {\n try {\n const result = await doWork(args);\n return result;\n } finally {\n span.end();\n }\n })\n );\n },\n});\n\n// Tool handlers are registered when the session is created.\nconst session = await client.createSession({ tools: [myTool] });\n```\n\n### Dependências por idioma\n\n| Linguagem | Dependência | Notes |\n| --------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Node.js | — | Nenhuma dependência; forneça `onGetTraceContext` callback para propagação de saída |\n| Python | `opentelemetry-api` | Instalar com o `pip install copilot-sdk[telemetry]` |\n| Go | `go.opentelemetry.io/otel` | Dependência necessária |\n| .NET | — | Usa `System.Diagnostics.Activity` integrado |\n| Java | `io.opentelemetry:opentelemetry-api` | Adicione esta dependência para a configuração baseada em SDK; a injeção do contexto de rastreamento é automática quando o agente Java do OpenTelemetry ou o SDK está configurado |\n\n## References\n\n* [Convenções Semânticas do OpenTelemetry GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)\n* [Convenções semânticas do OPENTelemetry MCP](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)\n* [OpenTelemetry Python SDK](https://opentelemetry.io/docs/instrumentation/python/)\n* documentação do SDK [Copilot](https://github.com/github/copilot-sdk)"}