{"meta":{"title":"Instrumentación de OpenTelemetry para el SDK de Copilot","intro":"En esta guía se muestra cómo agregar el seguimiento de OpenTelemetry a las aplicaciones del SDK de Copilot.","product":"GitHub Copilot","breadcrumbs":[{"href":"/es/copilot","title":"GitHub Copilot"},{"href":"/es/copilot/how-tos","title":"Procedimientos"},{"href":"/es/copilot/how-tos/copilot-sdk","title":"SDK de Copilot"},{"href":"/es/copilot/how-tos/copilot-sdk/observability","title":"Observability"},{"href":"/es/copilot/how-tos/copilot-sdk/observability/opentelemetry","title":"Opentelemetry"}],"documentType":"article"},"body":"# Instrumentación de OpenTelemetry para el SDK de Copilot\n\nEn esta guía se muestra cómo agregar el seguimiento de OpenTelemetry a las aplicaciones del SDK de Copilot.\n\n\n\n\n\n## Compatibilidad con telemetría integrada\n\nEl 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:\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### Opciones de TelemetryConfig\n\n| Opción | Node.js. | Python | Ir | .NET | Java | Óxido | Descripción |\n| -------------------------- | ---------------- | ----------------- | ---------------- | ---------------- | ---------------- | ----------------- | -------------------------------------------------------------------------------- |\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 |\n| Protocolo OTLP | `otlpProtocol` | `otlp_protocol` | `OTLPProtocol` | `OtlpProtocol` | `otlpProtocol` | `otlp_protocol` | Protocolo HTTP de OTLP para todas las señales: `\"http/json\"` o `\"http/protobuf\"` |\n| 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 |\n| Tipo de exportador | `exporterType` | `exporter_type` | `ExporterType` | `ExporterType` | `exporterType` | `exporter_type` | |\n| `\"otlp-http\"` o `\"file\"` | | | | | | | |\n| Nombre de origen | `sourceName` | `source_name` | `SourceName` | `SourceName` | `sourceName` | `source_name` | Nombre del ámbito de instrumentación |\n| Captura de contenido | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | `captureContent` | `capture_content` | Si se va a capturar el contenido del mensaje |\n\nEl 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.\n\n### Propagación del contexto de rastreo\n\n> **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.\n\nEl 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.\n\nPara 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).\n\n#### SDK → CLI (de salida)\n\nPara **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:\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** 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.\n\n#### CLI → SDK (entrante)\n\nCuando la CLI invoca un controlador de herramientas, `traceparent` y `tracestate` del tramo de la CLI están disponibles en todos los idiomas:\n\n* **Go**: El campo `ToolInvocation.TraceContext` es un `context.Context` con la traza ya restaurada; úselo directamente como elemento principal para sus spans.\n* **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.\n* **.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.\n* **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:\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### Dependencias por lenguaje\n\n| Language | Dependencia | Notas |\n| -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Node.js. | — | Sin dependencia; proporcione una devolución de llamada `onGetTraceContext` para la propagación saliente |\n| Python | `opentelemetry-api` | Instalar con `pip install copilot-sdk[telemetry]` |\n| Ir | `go.opentelemetry.io/otel` | Dependencia necesaria |\n| .NET | — | Utiliza la funcionalidad integrada `System.Diagnostics.Activity` |\n| 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 |\n\n## References\n\n* [Convenciones semánticas de OpenTelemetry GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/)\n* [Convenciones semánticas de MCP de OpenTelemetry](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)\n* [SDK de OpenTelemetry Python](https://opentelemetry.io/docs/instrumentation/python/)\n* Documentación del SDK de [Copilot](https://github.com/github/copilot-sdk)"}