# Instrumentação OpenTelemetry para o Copilot SDK

Este guia mostra como adicionar o rastreamento OpenTelemetry aos aplicativos SDK do Copilot.

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

## Suporte interno à telemetria

O 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:

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

<!-- docs-validate: skip -->

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  telemetry: {
    otlpEndpoint: "http://localhost:4318",
  },
});
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

<!-- docs-validate: skip -->

```python
from copilot import CopilotClient

client = CopilotClient(
    telemetry={
        "otlp_endpoint": "http://localhost:4318",
    },
)
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

<!-- docs-validate: skip -->

```golang
client := copilot.NewClient(&copilot.ClientOptions{
    Telemetry: &copilot.TelemetryConfig{
        OTLPEndpoint: "http://localhost:4318",
    },
})
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

```csharp
var client = new CopilotClient(new CopilotClientOptions
{
    Telemetry = new TelemetryConfig
    {
        OtlpEndpoint = "http://localhost:4318",
    },
});
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

<!-- docs-validate: skip -->

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setTelemetry(new TelemetryConfig()
        .setOtlpEndpoint("http://localhost:4318"))
);
```

</div>

<div class="ghd-codetab" data-lang="rust" data-label="Rust"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Rust</div>

<!-- docs-validate: skip -->

```rust
use github_copilot_sdk::{Client, ClientOptions, TelemetryConfig};

let client = Client::start(ClientOptions::new()
    .with_telemetry(TelemetryConfig::new()
        .with_otlp_endpoint("http://localhost:4318"))
).await?;
```

</div>

</div>

### Opções de TelemetryConfig

| Opção                     | Node.js          | Python            | Go               | .NET             | Java             | Rust              | Descrição                                                                    |
| ------------------------- | ---------------- | ----------------- | ---------------- | ---------------- | ---------------- | ----------------- | ---------------------------------------------------------------------------- |
| Ponto de extremidade OTLP | `otlpEndpoint`   | `otlp_endpoint`   | `OTLPEndpoint`   | `OtlpEndpoint`   | `otlpEndpoint`   | `otlp_endpoint`   | URL do ponto de extremidade OTLP HTTP                                        |
| Protocolo OTLP            | `otlpProtocol`   | `otlp_protocol`   | `OTLPProtocol`   | `OtlpProtocol`   | `otlpProtocol`   | `otlp_protocol`   | Protocolo HTTP OTLP para todos os sinais: `"http/json"` ou `"http/protobuf"` |
| Caminho do arquivo        | `filePath`       | `file_path`       | `FilePath`       | `FilePath`       | `filePath`       | `file_path`       | Caminho do arquivo para saída de rastreamento de linhas JSON                 |
| Tipo de exportador        | `exporterType`   | `exporter_type`   | `ExporterType`   | `ExporterType`   | `exporterType`   | `exporter_type`   |                                                                              |
| `"otlp-http"` ou `"file"` |                  |                   |                  |                  |                  |                   |                                                                              |
| Nome de origem            | `sourceName`     | `source_name`     | `SourceName`     | `SourceName`     | `sourceName`     | `source_name`     | Nome do escopo da instrumentação                                             |
| Capturar conteúdo         | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | `captureContent` | `capture_content` | Se o conteúdo da mensagem deve ser capturado                                 |

O 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.

### Propagação de contexto de traceamento

> **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.

O 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.

Para 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).

#### SDK → CLI (de saída)

Para **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.

<!-- docs-validate: skip -->

```typescript
import { CopilotClient } from "@github/copilot-sdk";
import { propagation, context } from "@opentelemetry/api";

const client = new CopilotClient({
  telemetry: { otlpEndpoint: "http://localhost:4318" },
  onGetTraceContext: () => {
    const carrier: Record<string, string> = {};
    propagation.inject(context.active(), carrier);
    return carrier; // { traceparent: "00-...", tracestate: "..." }
  },
});
```

Para **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.

#### CLI → SDK (de entrada)

Quando a CLI chama um manipulador de ferramenta, o `traceparent` e `tracestate` do span da CLI está disponível em todos os idiomas:

* ```
            **Vá para**: o campo `ToolInvocation.TraceContext` é um `context.Context` com o rastreamento já restaurado, use-o diretamente como pai dos seus spans.
  ```
* ```
            **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.
  ```
* ```
            **.NET**: o contexto de rastreamento é restaurado automaticamente via: `RestoreTraceContext()`instâncias filhas de `Activity` são associadas automaticamente como filhas ao span da CLI.
  ```
* **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:

<!-- docs-validate: skip -->

```typescript
import { defineTool } from "@github/copilot-sdk";
import { propagation, context, trace } from "@opentelemetry/api";

const myTool = defineTool("my-tool", {
  description: "Do work",
  handler: async (args, invocation) => {
    // Restore the CLI's trace context as the active context
    const carrier = {
      traceparent: invocation.traceparent,
      tracestate: invocation.tracestate,
    };
    const parentCtx = propagation.extract(context.active(), carrier);

    // Create a child span under the CLI's span
    const tracer = trace.getTracer("my-app");
    return context.with(parentCtx, () =>
      tracer.startActiveSpan("my-tool", async (span) => {
        try {
          const result = await doWork(args);
          return result;
        } finally {
          span.end();
        }
      })
    );
  },
});

// Tool handlers are registered when the session is created.
const session = await client.createSession({ tools: [myTool] });
```

### Dependências por idioma

| Linguagem | Dependência                          | Notes                                                                                                                                                                            |
| --------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.js   | —                                    | Nenhuma dependência; forneça `onGetTraceContext` callback para propagação de saída                                                                                               |
| Python    | `opentelemetry-api`                  | Instalar com o `pip install copilot-sdk[telemetry]`                                                                                                                              |
| Go        | `go.opentelemetry.io/otel`           | Dependência necessária                                                                                                                                                           |
| .NET      | —                                    | Usa `System.Diagnostics.Activity` integrado                                                                                                                                      |
| 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 |

## References

* [Convenções Semânticas do OpenTelemetry GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
* [Convenções semânticas do OPENTelemetry MCP](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
* [OpenTelemetry Python SDK](https://opentelemetry.io/docs/instrumentation/python/)
* documentação do SDK [Copilot](https://github.com/github/copilot-sdk)