Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# AWS X-Ray SDK para.NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
El X-Ray SDK para .NET es una biblioteca para instrumentar aplicaciones web de C\$1 .NET, aplicaciones web .NET Core y funciones de .NET Core. AWS Lambda Proporciona clases y métodos para generar y enviar datos de rastro al [daemon de X-Ray](xray-daemon.md). Incluye información sobre las solicitudes entrantes atendidas por la aplicación y las llamadas que la aplicación realiza a bases de datos descendentes Servicios de AWS APIs, web HTTP y SQL.
**nota**
El SDK de X-Ray para .NET es un proyecto de código abierto. Puedes seguir el proyecto y enviar las incidencias y solicitudes de cambios en GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-dotnet)- xray-sdk-dotnet
Para las aplicaciones web, comience por [añadir un controlador de mensajes a su configuración web](xray-sdk-dotnet-messagehandler.md) para realizar el seguimiento de las solicitudes entrantes. El controlador de mensajes crea un [segmento](xray-concepts.md#xray-concepts-segments) para cada solicitud rastreada y lo completa cuando se envía la respuesta. Mientras el segmento está abierto, puede utilizar los métodos del cliente del SDK para añadir información al segmento y crear subsegmentos para rastrear llamadas posteriores. El SDK también registra automáticamente las excepciones que produce su aplicación mientras el segmento está abierto.
En el caso de las funciones de Lambda llamadas por una aplicación o un servicio instrumentados, Lambda lee el [encabezado de rastreo](xray-concepts.md#xray-concepts-tracingheader) y rastrea automáticamente las solicitudes muestreadas. Para otras funciones, puede [configurar Lambda](xray-services-lambda.md) con el fin de muestrear y rastrear las solicitudes entrantes. En cualquier caso, Lambda crea el segmento y se lo proporciona al SDK de X-Ray.
**nota**
En Lambda, el SDK de X-Ray es opcional. Si no lo usa en su función, el mapa de servicio seguirá incluyendo un nodo para el servicio de Lambda y uno para cada función de Lambda. Al añadir el SDK, puede instrumentar el código de función para añadir subsegmentos al segmento de función registrado por Lambda. Para obtener más información, consulte [AWS Lambda y AWS X-Ray](xray-services-lambda.md).
A continuación, use el SDK de X-Ray para .NET con el fin de [instrumentar a sus clientes del AWS SDK para .NET](xray-sdk-dotnet-sdkclients.md). Cada vez que realizas una llamada a un servicio intermedio Servicio de AWS o a un recurso con un cliente instrumentado, el SDK registra la información sobre la llamada en un subsegmento. AWS los servicios y los recursos a los que accedes dentro de los servicios aparecen como nodos descendentes en el mapa de rastreo para ayudarte a identificar los errores y los problemas de limitación en las conexiones individuales.
El X-Ray SDK para .NET también proporciona instrumentación para llamadas posteriores a bases de datos [HTTP web APIs](xray-sdk-dotnet-httpclients.md) y [SQL](xray-sdk-dotnet-sqlqueries.md). El método de extensión `GetResponseTraced` para `System.Net.HttpWebRequest` rastrea llamadas HTTP salientes. Puede utilizar la versión de `SqlCommand` del SDK de X-Ray para .NET para instrumentar consultas SQL.
En cuanto empiece a utilizar el SDK, personalice su comportamiento [configurando la grabadora y el controlador de mensajes](xray-sdk-dotnet-configuration.md). Puede añadir complementos para registrar los datos sobre los recursos informáticos que ejecutan su aplicación, personalizar el comportamiento de muestreo mediante la definición de reglas de muestreo y definir el nivel de log para ver más o menos información del SDK en los logs de las aplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza en [anotaciones y metadatos](xray-sdk-dotnet-segment.md). Las anotaciones son pares sencillos de clave-valor que se indexan para su uso con [expresiones de filtro](xray-console-filters.md) para poder buscar rastros que contengan datos específicos. Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos, es decir, todo lo que se pueda serializar en JSON.
**Anotaciones y metadatos**
Las anotaciones y los metadatos son texto arbitrario que se agrega a los segmentos con el SDK de X-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadatos no se indexan pero se pueden ver en el segmento sin procesar con la consola o la API de X-Ray. Cualquier persona a la que conceda acceso de lectura a X-Ray puede ver estos datos.
Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitud puede contener un gran número de subsegmentos, uno para cada llamada realizada con un cliente instrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente en [subsegmentos personalizados](xray-sdk-dotnet-subsegments.md). Puede crear un subsegmento personalizado para una función completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en el subsegmento en lugar de escribirlo todo en el segmento principal.
Para acceder a documentos de referencia sobre las clases y los métodos de SDK, consulte lo siguiente:
+ [AWS X-Ray Referencia de la API de SDK for .NET](https://docs.aws.amazon.com//xray-sdk-for-dotnet/latest/reference)
+ [AWS X-Ray Referencia de API de SDK for .NET Core](https://docs.aws.amazon.com//xray-sdk-for-dotnetcore/latest/reference)
El mismo paquete admite tanto .NET como .NET Core, pero las clases que se utilizan varían. Los ejemplos de este capítulo contienen un enlace a la referencia del API de .NET, a menos que la clase sea específica de .NET Core.
## Requisitos
El X-Ray SDK para .NET requiere el.NET Framework 4.5 o una versión posterior AWS SDK para .NET y.
Para las aplicaciones y funciones de .NET Core, el SDK requiere .NET Core 2.0 o posterior.
## Integración del SDK de X-Ray para .NET en su aplicación
NuGet Utilícelo para agregar el X-Ray SDK para .NET a su aplicación.
**Para instalar el SDK de X-Ray para .NET con el administrador de NuGet paquetes de Visual Studio**
1. Elija **Tools**, **NuGet Package Manager** y **Manage NuGet Packages for Solution**.
1. Busque **AWSXRayRecorder**.
1. Elija el paquete y, a continuación, haga clic en **Install (Instalar)**.
## Administración de dependencias
El SDK de X-Ray para .NET está disponible en [Nuget](https://www.nuget.org/packages/AWSXRayRecorder/). Instale el SDK con el administrador de paquetes.
```
Install-Package AWSXRayRecorder -Version 2.10.1
```
El paquete NuGet `AWSXRayRecorder v2.10.1` tiene las siguientes dependencias:
### NET Framework 4.5
```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- AWSSDK.Core (>= 3.3.25.1)
|
|-- AWSXRayRecorder.Handlers.AspNet (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- EntityFramework (>= 6.2.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
|-- AWSXRayRecorder.Core (>= 2.10.1)
```
### NET Framework 2.0
```
AWSXRayRecorder (2.10.1)
|
|-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- AWSSDK.Core (>= 3.3.25.1)
| |-- Microsoft.AspNetCore.Http (>= 2.0.0)
| |-- Microsoft.Extensions.Configuration (>= 2.0.0)
| |-- System.Net.Http (>= 4.3.4)
|
|-- AWSXRayRecorder.Handlers.AspNetCore (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- Microsoft.AspNetCore.Http.Extensions (>= 2.0.0)
| |-- Microsoft.AspNetCore.Mvc.Abstractions (>= 2.0.0)
|
|-- AWSXRayRecorder.Handlers.AwsSdk (>= 2.8.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
|
|-- AWSXRayRecorder.Handlers.EntityFramework (>= 1.1.1)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- Microsoft.EntityFrameworkCore.Relational (>= 3.1.0)
|
|-- AWSXRayRecorder.Handlers.SqlServer (>= 2.7.3)
| |-- AWSXRayRecorder.Core (>= 2.10.1)
| |-- System.Data.SqlClient (>= 4.4.0)
|
|-- AWSXRayRecorder.Handlers.System.Net (>= 2.7.3)
|-- AWSXRayRecorder.Core (>= 2.10.1)
```
Para obtener más información sobre la administración de dependencias, consulte la documentación de Microsoft sobre la [dependencia de NuGet](https://docs.microsoft.com/en-us/dotnet/standard/library-guidance/dependencies) y la [resolución de dependencias de paquetes NuGet](https://docs.microsoft.com/en-us/nuget/concepts/dependency-resolution).
# Configuración del SDK de X-Ray para .NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Puede configurar el SDK de X-Ray para .NET mediante el uso de complementos a fin de incluir información sobre el servicio que sus aplicaciones ejecutan, modificar la conducta predeterminada de muestreo o agregar reglas de muestreo que se aplican a las solicitudes dirigidas a rutas específicas.
Para las aplicaciones web .NET, añada claves a la sección `appSettings` del archivo `Web.config`.
**Example Web.config**
```
```
Para .NET Core, cree un archivo denominado `appsettings.json` con una clave de nivel superior llamada `XRay`.
**Example .NET appsettings.json**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin",
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
A continuación, en el código de la aplicación, cree un objeto de configuración y utilícelo para inicializar la grabadora de X-Ray. Hágalo antes de [inicializar la grabadora](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs).
**Example .NET Core Program.cs: configuración de grabadora**
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder.InitializeInstance(configuration);
```
Si está instrumentando una aplicación web de .NET Core, también puede pasar el objeto de configuración al método `UseXRay` al [configurar el controlador de mensajes](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-startupcs). Para las funciones de Lambda utilice el método `InitializeInstance` como se muestra más arriba.
Para obtener más información acerca del API de configuración de .NET Core, consulte [Configurar una aplicación ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?tabs=basicconfiguration) en docs.microsoft.com.
**Topics**
+ [Plugins](#xray-sdk-dotnet-configuration-plugins)
+ [Reglas de muestreo](#xray-sdk-dotnet-configuration-sampling)
+ [Registro (.NET)](#xray-sdk-dotnet-configuration-logging)
+ [Registro (.NET Core)](#xray-sdk-dotnet-configuration-corelogging)
+ [Variables de entorno](#xray-sdk-dotnet-configuration-envvars)
## Plugins
Utilice complementos para agregar datos sobre el servicio que aloja su aplicación.
**Plugins**
+ Amazon EC2 : `EC2Plugin` agrega el ID de la instancia, la zona de disponibilidad y el grupo de CloudWatch registros.
+ Elastic Beanstalk: `ElasticBeanstalkPlugin` añade el nombre de entorno, la etiqueta de versión y el ID de implementación.
+ Amazon ECS: `ECSPlugin` agrega el ID de contenedor.
Para utilizar un complemento, configure el cliente del SDK de X-Ray para .NET añadiendo el ajuste `AWSXRayPlugins`. Si hay varios complementos para su aplicación, especifíquelos todos en la misma configuración, separados por comas.
**Example Web.config - complementos**
```
```
**Example .NET Core appsettings.json: complementos**
```
{
"XRay": {
"AWSXRayPlugins": "EC2Plugin,ElasticBeanstalkPlugin"
}
}
```
## Reglas de muestreo
El SDK utiliza las reglas de muestreo que define el usuario en la consola de X-Ray para determinar qué solicitudes registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. [Cree reglas adicionales en la consola de X-Ray](xray-console-sampling.md) para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.
El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, el SDK solo aplica la primera regla.
**nota**
Si el SDK no puede comunicarse con X-Ray para obtener las reglas de muestreo, vuelve a una regla local predeterminada de la primera solicitud cada segundo y del 5 % de las solicitudes adicionales por host. Esto puede ocurrir si el host no tiene permiso para llamar al muestreo APIs o no puede conectarse al daemon X-Ray, que actúa como proxy TCP para las llamadas a la API realizadas por el SDK.
También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar las reglas locales como respaldo para los casos en que el muestreo de X-Ray no esté disponible, o puede usar las reglas locales exclusivamente.
**Example sampling-rules.json**
```
{
"version": 2,
"rules": [
{
"description": "Player moves.",
"host": "*",
"http_method": "*",
"url_path": "/api/move/*",
"fixed_target": 0,
"rate": 0.05
}
],
"default": {
"fixed_target": 1,
"rate": 0.1
}
}
```
En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo `/api/move/`. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.
La desventaja de definir las reglas localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.
Sí AWS Lambda, no puedes modificar la frecuencia de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.
Para configurar reglas de respaldo, indique al SDK de X-Ray para .NET que cargue reglas de muestreo desde un archivo con la configuración `SamplingRuleManifest`.
**Example .NET Web.config: reglas de muestreo**
```
```
**Example .NET Core appsettings.json: reglas de muestreo**
```
{
"XRay": {
"SamplingRuleManifest": "sampling-rules.json"
}
}
```
Para utilizar solo reglas locales, cree la grabadora con una `LocalizedSamplingStrategy`. Si tiene reglas de copia de seguridad configuradas, elimine dicha configuración.
**Example .NET global.asax: reglas de muestreo locales**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("samplingrules.json")).Build();
AWSXRayRecorder.InitializeInstance(recorder: recorder);
```
**Example .NET Core Program.cs: reglas de muestreo locales**
```
var recorder = new AWSXRayRecorderBuilder().WithSamplingStrategy(new LocalizedSamplingStrategy("sampling-rules.json")).Build();
AWSXRayRecorder.InitializeInstance(configuration,recorder);
```
## Registro (.NET)
El SDK de X-Ray para .NET usa el mismo mecanismo de registro que [AWS SDK para .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Si ya configuró la aplicación para registrar la AWS SDK para .NET salida, la misma configuración se aplica a la salida del X-Ray SDK for .NET.
Para configurar el registro, añada una sección de configuración denominada `aws` al archivo `App.config` o `Web.config`.
**Example Web.config: registro**
```
...
```
Para obtener más información, consulte [Configuración del AWS SDK para .NET para su aplicación](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config.html) en la *Guía para desarrolladores del AWS SDK para .NET *.
## Registro (.NET Core)
El SDK de X-Ray para .NET usa las mismas opciones de registro que [AWS SDK para .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-config-other.html#config-setting-awslogging). Para configurar el registro para las aplicaciones .NET Core, transfiera la opción de registro al método `AWSXRayRecorder.RegisterLogger`.
Por ejemplo, para utilizar log4net, cree un archivo de configuración que defina el registrador, el formato de salida y la ubicación del archivo.
**Example .NET Core log4net.config**
```
```
A continuación, cree el registrador y aplique la configuración en el código del programa.
**Example .NET Core Program.cs: registro**
```
using log4net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
class Program
{
private static ILog log;
static Program()
{
var logRepository = LogManager.GetRepository(Assembly.GetEntryAssembly());
XmlConfigurator.Configure(logRepository, new FileInfo("log4net.config"));
log = LogManager.GetLogger(typeof(Program));
AWSXRayRecorder.RegisterLogger(LoggingOptions.Log4Net);
}
static void Main(string[] args)
{
...
}
}
```
Para obtener más información sobre cómo configurar log4net, consulte [Configuration](https://logging.apache.org/log4net/release/manual/configuration.html) en logging.apache.org.
## Variables de entorno
Puede usar variables de entorno para configurar el SDK de X-Ray para .NET. El SDK admite las siguientes variables.
+ `AWS_XRAY_TRACING_NAME`: establezca el nombre de servicio que el SDK utiliza para los segmentos. Anula el nombre de servicio que se ha establecido en la [estrategia de nomenclatura de segmento](xray-sdk-dotnet-messagehandler.md#xray-sdk-dotnet-messagehandler-naming) del filtro de servlet.
+ `AWS_XRAY_DAEMON_ADDRESS`: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK utiliza `127.0.0.1:2000` tanto para los datos de rastro (UDP) como para el muestreo (TCP). Use esta variable si ha configurado el daemon para que [escuche en un puerto diferente](xray-daemon-configuration.md) o si se ejecuta en un host diferente.
**Formato**
+ **El mismo puerto**: `address:port`
+ **Puertos diferentes**: `tcp:address:port udp:address:port`
+ `AWS_XRAY_CONTEXT_MISSING`: establezca esta opción en `RUNTIME_ERROR` para generar excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.
**Valores válidos**
+ `RUNTIME_ERROR`: lance una excepción de tiempo de ejecución.
+ `LOG_ERROR`: registre un error y continúe (predeterminado).
+ `IGNORE_ERROR`: ignore el error y continúe.
Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o en el código que inicia un nuevo subproceso.
# Instrumentación de las solicitudes HTTP entrantes con el SDK de X-Ray para .NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Puede usar el SDK de X-Ray para rastrear las solicitudes HTTP entrantes que su aplicación sirve en una instancia EC2 de Amazon EC2 AWS Elastic Beanstalk o Amazon ECS.
Utilice un controlador de mensajes para instrumentar las solicitudes HTTP entrantes. Cuando agrega el controlador de mensajes de X-Ray a su aplicación, el SDK de X-Ray para .NET crea un segmento para cada solicitud muestreada. Este segmento incluye el momento, el método y la disposición de la solicitud HTTP. La instrumentación adicional crea subsegmentos en este segmento.
**nota**
En el AWS Lambda caso de las funciones, Lambda crea un segmento para cada solicitud muestreada. Para obtener más información, consulte [AWS Lambda y AWS X-Ray](xray-services-lambda.md).
Cada segmento tiene un nombre que identifica la aplicación en el mapa de servicio. El nombre del segmento se puede asignar de forma estática o se puede configurar el SDK para que le asigne un nombre dinámico en función del encabezado del host de la solicitud entrante. La nomenclatura dinámica permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar un nombre predeterminado si el nombre no coincide con el patrón esperado (por ejemplo, si el encabezado del host está falsificado).
**Solicitudes reenviadas**
Si un equilibrador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray toma la IP de cliente del encabezado `X-Forwarded-For` de la solicitud en lugar de tomar la IP de origen del paquete IP. La IP de cliente que se graba para una solicitud reenviada puede estar falsificada, por lo que no se debe confiar en ella.
El controlador de mensajes crea un segmento para cada solicitud entrante con un bloque `http` que contiene la siguiente información:
+ **Método HTTP**: GET, POST, PUT, DELETE, etc.
+ **Dirección del cliente**: la dirección IP del cliente que envió la solicitud.
+ **Código de respuesta**: el código de respuesta HTTP para la solicitud finalizada.
+ **Intervalo**: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la respuesta).
+ **Agente del usuario**: el `user-agent` de la solicitud.
+ **Longitud del contenido**: la `content-length` de la respuesta.
**Topics**
+ [Instrumentación de las solicitudes entrantes (.NET)](#xray-sdk-dotnet-messagehandler-globalasax)
+ [Instrumentación de las solicitudes entrantes (.NET Core)](#xray-sdk-dotnet-messagehandler-startupcs)
+ [Configuración de una estrategia de nomenclatura de segmentos](#xray-sdk-dotnet-messagehandler-naming)
## Instrumentación de las solicitudes entrantes (.NET)
Para instrumentar las solicitudes que atiende su aplicación, llame a `RegisterXRay` en el método `Init` del archivo `global.asax`.
**Example global.asax: controlador de mensajes**
```
using System.Web.Http;
using [Amazon.XRay.Recorder.Handlers.AspNet](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_AspNet.htm);
namespace SampleEBWebApplication
{
public class MvcApplication : System.Web.HttpApplication
{
public override void Init()
{
base.Init();
AWSXRayASPNET.RegisterXRay(this, "MyApp");
}
}
}
```
## Instrumentación de las solicitudes entrantes (.NET Core)
Para instrumentar las solicitudes atendidas por la aplicación, llame al método `UseXRay` antes que a cualquier otro middleware del método `Configure` de su clase Startup, ya que lo ideal es que el middleware X-Ray sea el primer middleware en procesar la solicitud y el último en procesar la respuesta en el proceso.
**nota**
En el caso de .NET Core 2.0, si tiene un método `UseExceptionHandler` en la aplicación, asegúrese de llamar a `UseXRay` después del método `UseExceptionHandler` para asegurarse de que se registren las excepciones.
**Example Startup.cs**
```
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseXRay("MyApp");
// additional middleware
...
}
```
```
using Microsoft.AspNetCore.Builder;
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseExceptionHandler("/Error");
app.UseXRay("MyApp");
// additional middleware
...
}
```
El método `UseXRay` también puede tomar un [objeto de configuración](xray-sdk-dotnet-configuration.md) como segundo argumento.
```
app.UseXRay("MyApp", configuration);
```
## Configuración de una estrategia de nomenclatura de segmentos
AWS X-Ray utiliza un *nombre de servicio* para identificar su aplicación y distinguirla del resto de aplicaciones, bases de datos, AWS recursos externos APIs y que utiliza su aplicación. Cuando el SDK de X-Ray genera segmentos para las solicitudes entrantes, registra el nombre del servicio de la aplicación en el [campo de nombre](xray-api-segmentdocuments.md#api-segmentdocuments-fields) del segmento.
El SDK de X-Ray puede nombrar los segmentos utilizando el nombre de host en el encabezado de la solicitud HTTP. Sin embargo, este encabezado se puede falsificar, lo que podría provocar nodos inesperados en el mapa de servicio. Para evitar que el SDK nombre los segmentos de forma incorrecta debido a que las solicitudes tienen encabezados de host falsificados, debe especificar un nombre predeterminado para las solicitudes entrantes.
Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que utilice una estrategia de nomenclatura dinámica que refleje esto en los nombres de los segmentos. Una estrategia de nomenclatura dinámica permite al SDK usar el nombre de host para las solicitudes que coinciden con un patrón esperado y aplicar el nombre predeterminado a las solicitudes que no coincidan.
Por ejemplo, es posible que tenga una sola aplicación que atienda solicitudes a tres subdominios: `www.example.com`, `api.example.com` y `static.example.com`. Puede usar una estrategia de nomenclatura dinámica con el patrón `*.example.com` para identificar los segmentos de cada subdominio con un nombre diferente, lo que da como resultado tres nodos de servicio en el mapa de servicio. Si su aplicación recibe solicitudes con un nombre de host que no coincide con el patrón, verá un cuarto nodo en el mapa de servicio con el nombre alternativo que especifique.
Para utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de la aplicación cuando inicialice el controlador de mensajes, tal y como se muestra en [la sección anterior](#xray-sdk-dotnet-messagehandler-globalasax). Esto tiene el mismo efecto que crear un [https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_FixedSegmentNamingStrategy.htm) y pasárselo al método `RegisterXRay`.
```
AWSXRayASPNET.RegisterXRay(this, new FixedSegmentNamingStrategy("MyApp"));
```
**nota**
Puede anular el nombre de servicio predeterminado que ha definido en el código mediante la `AWS_XRAY_TRACING_NAME`variable de entorno[Variables de entorno](xray-sdk-dotnet-configuration.md#xray-sdk-dotnet-configuration-envvars).
Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de host y un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con el patrón. Para asignar nombres a los segmentos dinámicamente, cree un objeto [https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/T_Amazon_XRay_Recorder_Core_Strategies_DynamicSegmentNamingStrategy.htm) y páseselo al método `RegisterXRay`.
```
AWSXRayASPNET.RegisterXRay(this, new DynamicSegmentNamingStrategy("MyApp", "*.example.com"));
```
# Rastreo de llamadas AWS del SDK con el X-Ray SDK para .NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
[Cuando la aplicación realiza llamadas Servicios de AWS para almacenar datos, escribir en una cola o enviar notificaciones, el X-Ray SDK for .NET rastrea las llamadas en sentido descendente en subsegmentos.](xray-sdk-dotnet-subsegments.md) El rastreo Servicios de AWS y los recursos a los que accede dentro de esos servicios (por ejemplo, un bucket de Amazon S3 o una cola de Amazon SQS) aparecen como nodos descendentes en el mapa de rastreo de la consola X-Ray.
Puede instrumentar a todos sus AWS SDK para .NET clientes llamando `RegisterXRayForAllServices` antes de crearlos.
**Example SampleController.cs: instrumentación de cliente de DynamoDB**
```
using Amazon;
using Amazon.Util;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DocumentModel;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.AwsSdk](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_AwsSdk.htm);
namespace SampleEBWebApplication.Controllers
{
public class SampleController : ApiController
{
AWSSDKHandler.RegisterXRayForAllServices();
private static readonly Lazy LazyDdbClient = new Lazy(() =>
{
var client = new AmazonDynamoDBClient(EC2InstanceMetadata.Region ?? RegionEndpoint.USEast1);
return client;
});
```
Si desea instrumentar clientes para algunos servicios y no para otros, llame a `RegisterXRay` en lugar de `RegisterXRayForAllServices`. Reemplace el texto resaltado por el nombre de la interfaz de cliente del servicio.
```
AWSSDKHandler.RegisterXRay()
```
Para todos los servicios, puede ver el nombre de la API a la que se llama en la consola de X-Ray. Para un subconjunto de servicios, el SDK de X-Ray agrega información al segmento para proporcionar una mayor granularidad en el mapa de servicio.
Por ejemplo, cuando realiza una llamada con un cliente instrumentado de DynamoDB, el SDK agrega el nombre de tabla al segmento para las llamadas que se dirigen a una tabla. En la consola, cada tabla aparece como nodo independiente en el mapa de servicio, con un nodo genérico de DynamoDB para las llamadas que no se dirigen a una tabla.
**Example Subsegmento para una llamada a DynamoDB con el fin de guardar un elemento**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales en el mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico en el servicio.
+ **Amazon DynamoDB**: nombre de tabla
+ **Amazon Simple Storage Service**: nombre de bucket y de clave
+ **Amazon Simple Queue Service**: nombre de cola
# Rastreo de llamadas a servicios web HTTP posteriores con el SDK de X-Ray para .NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Cuando tu aplicación realiza llamadas a microservicios o a HTTP públicos APIs, puedes usar el método de `GetResponseTraced` extensión del SDK de X-Ray para .NET `System.Net.HttpWebRequest` para instrumentar esas llamadas y añadir la API al gráfico del servicio como un servicio descendente.
**Example HttpWebRequest**
```
using System.Net;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.System.Net](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_System_Net.htm);
private void MakeHttpRequest()
{
HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://names.example.com/api");
request.GetResponseTraced();
}
```
Para las llamadas asíncronas, utilice `GetAsyncResponseTraced`.
```
request.GetAsyncResponseTraced();
```
Si utiliza [https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx](https://msdn.microsoft.com/en-us/library/system.net.http.httpclient.aspx), utilice el controlador de delegación `HttpClientXRayTracingHandler` para registrar las llamadas.
**Example HttpClient**
```
using System.Net.Http;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.System.Net](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_System_Net.htm);
private void MakeHttpRequest()
{
var httpClient = new HttpClient(new HttpClientXRayTracingHandler(new HttpClientHandler()));
httpClient.GetAsync(URL);
}
```
Cuando se instrumenta una llamada a un API web posterior, el del SDK de X-Ray para .NET registra un subsegmento con información sobre la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar un segmento inferido para la API.
**Example Subsegmento para una llamada HTTP posterior**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento inferido para una llamada HTTP posterior**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Rastreo de consultas SQL con el SDK de X-Ray para .NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
El SDK de X-Ray para .NET proporciona una clase de encapsulamiento `System.Data.SqlClient.SqlCommand` denominada `TraceableSqlCommand` que puede utilizar en lugar de `SqlCommand`. Puede inicializar un comando SQL con la clase `TraceableSqlCommand`.
## Seguimiento de consultas SQL con métodos síncronos y asíncronos
Los siguientes ejemplos muestran cómo utilizar `TraceableSqlCommand` para rastrear automáticamente las consultas de SQL Server de forma síncrona y asíncrona.
**Example `Controller.cs`: instrumentación de cliente de SQL (síncrono)**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
using (var sqlConnection = new SqlConnection(connectionString))
using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
{
sqlCommand.Connection.Open();
sqlCommand.ExecuteNonQuery();
}
}
```
Puede ejecutar la consulta de forma asíncrona utilizando el método `ExecuteReaderAsync`.
**Example `Controller.cs`: instrumentación de clientes de SQL (asíncronos)**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
using (var sqlConnection = new SqlConnection(connectionString))
using (var sqlCommand = new TraceableSqlCommand("SELECT " + id, sqlConnection))
{
await sqlCommand.ExecuteReaderAsync();
}
}
```
## Recopilación de consultas SQL realizadas a SQL Server
Puede habilitar la captura de `SqlCommand.CommandText` como parte del subsegmento creado por la consulta SQL. `SqlCommand.CommandText` aparece como el campo `sanitized_query` en el JSON del subsegmento. De forma predeterminada, esta característica está deshabilitada por motivos de seguridad.
**nota**
No habilite la característica de recopilación si está incluyendo información confidencial como texto sin cifrar en sus consultas SQL.
Puede habilitar la recopilación de consultas SQL de dos formas:
+ Establezca la propiedad `CollectSqlQueries` en `true` en la configuración global de su aplicación.
+ Establezca el parámetro `collectSqlQueries` de la instancia `TraceableSqlCommand` en `true` para recopilar llamadas dentro de la instancia.
### Habilite la propiedad global CollectSqlQueries
Los siguientes ejemplos muestran cómo habilitar la propiedad `CollectSqlQueries` para .NET y .NET Core.
------
#### [ .NET ]
Para establecer la propiedad `CollectSqlQueries` en `true` en la configuración global de su aplicación en .NET, modifique el `appsettings` de su archivo `Web.config` o `App.config`, tal y como se muestra.
**Example `App.config` o bien `Web.config`: habilitación global de la recopilación de consultas SQL**
```
```
------
#### [ .NET Core ]
Para establecer la propiedad `CollectSqlQueries` en `true` en la configuración global de su aplicación en .NET Core, modifique el archivo `appsettings.json` en la clave de X-Ray, tal y como se muestra.
**Example `appsettings.json`: habilitación global de la recopilación de consultas SQL**
```
{
"XRay": {
"CollectSqlQueries":"true"
}
}
```
------
### Habilite el collectSqlQueries parámetro
Puede establecer el parámetro `collectSqlQueries` en la instancia `TraceableSqlCommand` en `true` para recopilar el texto de consulta SQL para las consultas de SQL Server realizadas con esa instancia. Si se establece el parámetro en `false` se deshabilita la característica `CollectSqlQuery` para la instancia `TraceableSqlCommand`.
**nota**
El valor de `collectSqlQueries` en la instancia `TraceableSqlCommand` anula el valor establecido en la configuración global de la propiedad `CollectSqlQueries`.
**Example Ejemplo `Controller.cs`: habilitación de la recopilación de consultas SQL para la instancia**
```
using Amazon;
using Amazon.Util;
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
using [Amazon.XRay.Recorder.Handlers.SqlServer](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Handlers_SqlServer.htm);
private void QuerySql(int id)
{
var connectionString = ConfigurationManager.AppSettings["RDS_CONNECTION_STRING"];
using (var sqlConnection = new SqlConnection(connectionString))
using (var command = new TraceableSqlCommand("SELECT " + id, sqlConnection, collectSqlQueries: true))
{
command.ExecuteNonQuery();
}
}
```
# Creación de subsegmentos adicionales
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Los subsegmentos amplían el [segmento](xray-concepts.md#xray-concepts-segments) de un rastro con detalles sobre el trabajo realizado para atender una solicitud. Cada vez que usted realiza una llamada con un cliente instrumentado, el SDK de X-Ray registra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agrupar otros subsegmentos, medir el rendimiento de una sección de código o registrar anotaciones y metadatos.
Para administrar los subsegmentos, utilice los métodos `BeginSubsegment` y `EndSubsegment`. Realice el trabajo que desee en el subsegmento en un bloque `try` y utilice `AddException` para rastrear excepciones. Llame a `EndSubsegment` en un bloque `finally` para asegurarse de que el subsegmento está cerrado.
**Example Controller.cs: subsegmento personalizado**
```
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
try
{
DoWork();
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally
{
AWSXRayRecorder.Instance.EndSubsegment();
}
```
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el SDK de X-Ray para .NET genera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización.
**Example Subsegmentos con metadatos**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
# Agregue anotaciones y metadatos a los segmentos con el SDK de X-Ray para .NET
**nota**
Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry
Puede registrar información adicional acerca de las solicitudes, el entorno o su aplicación con anotaciones y metadatos. Puede añadir anotaciones y metadatos a los segmentos que crea el SDK de X-Ray o a los subsegmentos personalizados que cree usted mismo.
Las **anotaciones** son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotaciones se indexan para su uso con [expresiones de filtro](xray-console-filters.md). Utilice anotaciones para registrar los datos que desee utilizar para agrupar rastros en la consola o cuando llame a la API de [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
Los **metadatos** son pares de clave-valor con valores de cualquier tipo, por ejemplo objetos y listas, pero que no se indexan para utilizarlos con expresiones de filtro. Utilice los metadatos para registrar datos adicionales que desee almacenar en el rastro, pero que no necesite usar para hacer búsquedas.
**Topics**
+ [Registro de anotaciones con el SDK de X-Ray para .NET](#xray-sdk-dotnet-segment-annotations)
+ [Registro de metadatos con el SDK de X-Ray para .NET](#xray-sdk-dotnet-segment-metadata)
## Registro de anotaciones con el SDK de X-Ray para .NET
Utilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar para las búsquedas.
Se requiere lo siguiente para todas las anotaciones de X-Ray:
**Requisitos de anotación**
+ **Claves**: la clave de una anotación de X-Ray puede contener hasta 500 caracteres alfanuméricos. No se pueden usar espacios ni símbolos, excepto el punto (.)
+ **Valores**: el valor de una anotación de X-Ray puede contener hasta 1000 caracteres Unicode.
+ Número de **anotaciones**: se pueden utilizar hasta 50 anotaciones por rastro.
**Para grabar anotaciones fuera de una función AWS Lambda**
1. Obtenga una instancia de `AWSXRayRecorder`.
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
```
1. Llame a `addAnnotation` con una clave de cadena y un valor booleano, Int32, Int64, doble o de cadena.
```
recorder.AddAnnotation("mykey", "my value");
```
El siguiente ejemplo muestra cómo llamar a `putAnnotation` con una clave de cadena que incluye un punto y un valor booleano, numérico o de cadena.
```
document.putAnnotation("testkey.test", "my value");
```
**Para grabar anotaciones dentro de una función AWS Lambda**
Tanto los segmentos como los subsegmentos de una función de Lambda se administran mediante el entorno de tiempo de ejecución de Lambda. Si desea añadir una anotación a un segmento o subsegmento dentro de una función de Lambda, debe hacer lo siguiente:
1. Cree el segmento o subsegmento dentro de la función de Lambda.
1. Añada la anotación al segmento o subsegmento.
1. Finalice el segmento o subsegmento.
En el siguiente código de ejemplo, se muestra cómo agregar una anotación a un subsegmento de una función de Lambda:
```
#Create the subsegment
AWSXRayRecorder.Instance.BeginSubsegment("custom method");
#Add an annotation
AWSXRayRecorder.Instance.AddAnnotation("My", "Annotation");
try
{
YourProcess(); #Your function
}
catch (Exception e)
{
AWSXRayRecorder.Instance.AddException(e);
}
finally #End the subsegment
{
AWSXRayRecorder.Instance.EndSubsegment();
}
```
El SDK de X-Ray registra las anotaciones como pares de clave-valor en un objeto `annotations` del documento de segmento. Si llama dos veces a una operación `addAnnotation` con la misma clave, se sobrescribe el valor previamente registrado en ese segmento o subsegmento.
Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra clave `annotation[key]` en una [expresión de filtro](xray-console-filters.md).
## Registro de metadatos con el SDK de X-Ray para .NET
Utilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexar para emplearlos en las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquier otro objeto que se pueda serializar en un objeto o matriz JSON.
**Para registrar metadatos**
1. Obtenga una instancia de `AWSXRayRecorder`, tal como se muestra en el siguiente código de ejemplo:
```
using [Amazon.XRay.Recorder.Core](https://docs.aws.amazon.com/xray-sdk-for-dotnet/latest/reference/html/N_Amazon_XRay_Recorder_Core.htm);
...
AWSXRayRecorder recorder = AWSXRayRecorder.Instance;
```
1. Llame a `AddMetadata` con un espacio de nombres de cadena, una clave de cadena y un valor de objeto, como se indica en el siguiente código de ejemplo:
```
recorder.AddMetadata("my namespace", "my key", "my value");
```
También puede llamar a la operación `AddMetadata` con solo un par de clave-valor, como se muestra en el siguiente código de ejemplo:
```
recorder.AddMetadata("my key", "my value");
```
Si no especifica un valor para el espacio de nombres, el SDK de X-Ray utiliza `default`. Si llama dos veces a una operación `AddMetadata` con la misma clave, se sobrescribe el valor previamente registrado en ese segmento o subsegmento.