# Instrumentación de OpenTelemetry para el SDK de Copilot

En esta guía se muestra cómo agregar el seguimiento de OpenTelemetry a las aplicaciones del SDK de Copilot.

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

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

## Compatibilidad con telemetría integrada

El SDK tiene compatibilidad integrada para configurar OpenTelemetry en el proceso de la CLI y propagar el contexto de seguimiento de W3C entre el SDK y la CLI. Proporcione un `TelemetryConfig` al crear el cliente para habilitarlo:

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

### Opciones de TelemetryConfig

| Opción                     | Node.js.         | Python            | Ir               | .NET             | Java             | Óxido             | Descripción                                                                      |
| -------------------------- | ---------------- | ----------------- | ---------------- | ---------------- | ---------------- | ----------------- | -------------------------------------------------------------------------------- |
| Punto de conexión de OTLP  | `otlpEndpoint`   | `otlp_endpoint`   | `OTLPEndpoint`   | `OtlpEndpoint`   | `otlpEndpoint`   | `otlp_endpoint`   | Dirección URL del punto de conexión HTTP de OTLP                                 |
| Protocolo OTLP             | `otlpProtocol`   | `otlp_protocol`   | `OTLPProtocol`   | `OtlpProtocol`   | `otlpProtocol`   | `otlp_protocol`   | Protocolo HTTP de OTLP para todas las señales: `"http/json"` o `"http/protobuf"` |
| Ruta de acceso del archivo | `filePath`       | `file_path`       | `FilePath`       | `FilePath`       | `filePath`       | `file_path`       | Ruta de acceso de archivo para salida de seguimiento de líneas JSON              |
| Tipo de exportador         | `exporterType`   | `exporter_type`   | `ExporterType`   | `ExporterType`   | `exporterType`   | `exporter_type`   |                                                                                  |
| `"otlp-http"` o `"file"`   |                  |                   |                  |                  |                  |                   |                                                                                  |
| Nombre de origen           | `sourceName`     | `source_name`     | `SourceName`     | `SourceName`     | `sourceName`     | `source_name`     | Nombre del ámbito de instrumentación                                             |
| Captura de contenido       | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | `captureContent` | `capture_content` | Si se va a capturar el contenido del mensaje                                     |

El campo de protocolo OTLP configura el exportador `"otlp-http"` de la CLI para todas las señales. Déjelo sin definir para usar el valor predeterminado de la CLI, o configúrelo como `"http/protobuf"` para exportar en formato protobuf a través de HTTP.

### Propagación del contexto de rastreo

> **La mayoría de los usuarios no necesitan esto.** La `TelemetryConfig` anterior es lo único que necesita para recopilar seguimientos desde la CLI. La propagación del contexto de seguimiento que se describe en esta sección es una **característica avanzada** para las aplicaciones que crean sus propios intervalos de OpenTelemetry y quieren que aparezcan en el **mismo seguimiento distribuido** que los intervalos de la CLI.

El SDK puede propagar el contexto de seguimiento de W3C (`traceparent`/`tracestate`) en cargas JSON-RPC para que las trazas de la aplicación y las trazas de la CLI estén vinculadas en un seguimiento distribuido. Esto resulta útil cuando, por ejemplo, desea ver un intervalo «controlar llamada a herramienta» de su aplicación anidado dentro del intervalo «ejecutar herramienta» de la CLI, o mostrar la llamada del SDK como elemento secundario del intervalo de control de solicitudes.

Para atribuir costes junto con los seguimientos, suscríbase a `assistant.usage`eventos e inspeccione `apiEndpoint` (`AssistantUsageApiEndpoint`) para comprobar si un turno utilizó Finalizaciones de chat, Respuestas o Mensajes de Anthropic; consulte [TÍTULO AUTOMÁTICO](/es/copilot/how-tos/copilot-sdk/features/streaming-events).

#### SDK → CLI (de salida)

Para **Node.js**, proporcione una devolución de llamada `onGetTraceContext` en las opciones del cliente. Solo es necesario si la aplicación ya utiliza `@opentelemetry/api` y desea vincular los intervalos con los intervalos de la CLI. El SDK llama a esta devolución de llamada antes que a las `session.create`, `session.resume` y `session.send` RPC:

<!-- 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** y **.NET**, la inyección del contexto de trazas es automática cuando está configurada la API correspondiente de OpenTelemetry/Activity; no se necesita ninguna función de callback.

#### CLI → SDK (entrante)

Cuando la CLI invoca un controlador de herramientas, `traceparent` y `tracestate` del tramo de la CLI están disponibles en todos los idiomas:

* **Go**: El campo `ToolInvocation.TraceContext` es un `context.Context` con la traza ya restaurada; úselo directamente como elemento principal para sus spans.
* **Python**: El contexto de seguimiento se restaura automáticamente alrededor del controlador mediante`trace_context()`; los intervalos secundarios se vinculan automáticamente al intervalo de la CLI.
* **.NET**: El contexto de seguimiento se restaura automáticamente mediante `RestoreTraceContext()`; las instancias secundarias de `Activity` se vinculan automáticamente al intervalo de la CLI.
* **Node.js**: Dado que el SDK no tiene ninguna dependencia de OpenTelemetry, `traceparent` y `tracestate` se pasan como cadenas sin procesar en el objeto `ToolInvocation`. Restaure el contexto manualmente si es necesario:

<!-- 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] });
```

### Dependencias por lenguaje

| Language | Dependencia                          | Notas                                                                                                                                                                             |
| -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Node.js. | —                                    | Sin dependencia; proporcione una devolución de llamada `onGetTraceContext` para la propagación saliente                                                                           |
| Python   | `opentelemetry-api`                  | Instalar con `pip install copilot-sdk[telemetry]`                                                                                                                                 |
| Ir       | `go.opentelemetry.io/otel`           | Dependencia necesaria                                                                                                                                                             |
| .NET     | —                                    | Utiliza la funcionalidad integrada `System.Diagnostics.Activity`                                                                                                                  |
| Java     | `io.opentelemetry:opentelemetry-api` | Añada esta dependencia para la configuración basada en el SDK; la inserción del contexto de rastreo es automática cuando se configura el agente de Java de OpenTelemetry o el SDK |

## References

* [Convenciones semánticas de OpenTelemetry GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
* [Convenciones semánticas de MCP de OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
* [SDK de OpenTelemetry Python](https://opentelemetry.io/docs/instrumentation/python/)
* Documentación del SDK de [Copilot](https://github.com/github/copilot-sdk)