Después de configurar la biblioteca de rastreo con tu código y de configurar el Agent para recopilar datos de APM, también puedes configurar la biblioteca de rastreo como prefieras e incluir la configuración del Etiquetado de servicios unificado.

Establecer precedencia de la configuración del rastreador de .NET Core

Puedes definir parámetros de configuración en el rastreador de .NET utilizando cualquiera de los siguientes métodos:

Para configurar el rastreador mediante variables de entorno, establece las variables antes de lanzar la aplicación instrumentada. Para saber cómo configurar las variables de entorno en diferentes entornos, consulta Proceso de configuración de las variables de entorno.

Para configurar el rastreador en el código de la aplicación, crea una instancia TracerSettings a partir de las fuentes de configuración predeterminadas. Establece las propiedades de esta instancia TracerSettings antes de llamar a Tracer.Configure(). Por ejemplo:

Nota: La configuración debe establecerse en TracerSettings antes de crear el rastreador. Los cambios realizados en las propiedades de TracerSettings después de crear el rastreador se ignoran.
using Datadog.Trace;
using Datadog.Trace.Configuration;

// fuentes de configuración de lectura por defecto (variables de entorno o datadog.json)
var settings = TracerSettings.FromDefaultSources();

// cambia algunos ajustes
settings.Environment = "prod";
settings.ServiceName = "MyService";
settings.ServiceVersion = "abc123";
settings.Exporter.AgentUri = new Uri("http://localhost:8126/");

// configura los ajustes globales del rastreador
Tracer.Configure(settings);

Para configurar el rastreador mediante un archivo JSON, crea datadog.json en el directorio de la aplicación instrumentada. El objeto JSON raíz debe ser un objeto con un par clave-valor para cada ajuste. Por ejemplo:

{
  "DD_TRACE_AGENT_URL": "http://localhost:8126",
  "DD_ENV": "prod",
  "DD_SERVICE": "MyService",
  "DD_VERSION": "abc123",
}

Ajustes de configuración

Nota: En Linux, los nombres de las variables de entorno distinguen entre mayúsculas y minúsculas.

Con los métodos descritos anteriormente, personaliza tu configuración de rastreo con las siguientes variables. Utiliza el nombre de la variable de entorno (por ejemplo, DD_TRACE_AGENT_URL) cuando configures las variables de entorno o los archivos de configuración. Utiliza la propiedad TracerSettings (por ejemplo, Exporter.AgentUri) cuando cambies la configuración en el código.

Etiquetado de servicios unificado

Para utilizar el etiquetado de servicios unificado, configura los siguientes ajustes para tus servicios:

DD_ENV
Propiedad en TracerSettings: Environment
Si se especifica, añade la etiqueta env con el valor especificado a todos los tramos generados. Añadido en la versión 1.17.0.
DD_SERVICE
Propiedad en TracerSettings: ServiceName
Si se especifica, establece el nombre del servicio. De lo contrario, el rastreador de .NET intenta determinar el nombre del servicio automáticamente a partir del nombre de la aplicación (nombre de la aplicación IIS, ensamblador del proceso de entrada, o nombre del proceso). Añadido en la versión 1.17.0.
DD_VERSION
Propiedad en TracerSettings: ServiceVersion
Si se especifica, establece la versión del servicio. Añadido en la versión 1.17.0.

Configuración opcional

Las siguientes variables de configuración están disponibles tanto para la instrumentación automática como para la personalizada:

DD_TRACE_AGENT_URL
Propiedad en TracerSettings: Exporter.AgentUri
Establece el endpoint de la URL donde se envían trazas. Sustituye a DD_AGENT_HOST y DD_TRACE_AGENT_PORT si están establecidos. Si la configuración del Agent establece receiver_port o DD_APM_RECEIVER_PORT a algo distinto del valor predeterminado 8126, entonces DD_TRACE_AGENT_PORT o DD_TRACE_AGENT_URL deben coincidir con él.
Puede contener una ruta de Unix Domain Socket (UDS) anteponiendo la ruta unix://.
Ten en cuenta que UDS solo es compatible con .NET Core 3.1 y versiones posteriores.
Predeterminado: http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT> si están configurados, unix:///var/run/datadog/apm.socket si el archivo existe, o http://localhost:8126.
DD_AGENT_HOST
establece el host donde el Agent escucha conexiones. Puede ser un nombre de host o una dirección IP. Utiliza DD_TRACE_AGENT_URL, que tiene prioridad sobre este parámetro.
Predeterminado: localhost
DD_TRACE_AGENT_PORT
establece el puerto TCP en el que el Agent escucha conexiones. Utiliza DD_TRACE_AGENT_URL, que tiene prioridad sobre este parámetro. Si la configuración del Agent establece receiver_port o DD_APM_RECEIVER_PORT a algo distinto del valor predeterminado 8126, entonces DD_TRACE_AGENT_PORT o DD_TRACE_AGENT_URL deben coincidir con él.
Predeterminado: 8126
DD_TRACE_SAMPLE_RATE
Propiedad en TracerSettings: GlobalSamplingRate
Predeterminado: se establece por defecto en la tasa devuelta por el Datadog Agent
Activa el control de la tasa de ingesta. Este parámetro es un valor flotante que representa el porcentaje de tramos a muestrear. Los valores válidos van de 0.0 a 1.0. Para más información, consulta Mecanismos de ingesta.

Fase beta: a partir de la versión 2.35.0, si la configuración remota del Agent está habilitada donde se ejecuta este servicio, puedes establecer DD_TRACE_SAMPLE_RATE en la interfaz de usuario del Catálogo de servicios.
DD_TRACE_SAMPLING_RULES
Propiedad en TracerSettings: CustomSamplingRules
Predeterminado: null
Una matriz de objetos JSON. Cada objeto debe tener una sample_rate. Los campos name y service son opcionales. El valor sample_rate debe estar comprendido entre 0.0 y 1.0 (ambos inclusive). Las reglas se aplican en el orden configurado para determinar la frecuencia de muestreo de la traza. Para más información, consulta Mecanismos de ingesta.
Ejemplos:
  • Configura la frecuencia de muestreo en 20%: [{"sample_rate": 0.2}]
  • Ajusta la frecuencia de muestreo al 10% para servicios que empiece por ‘a’ y nombre de tramo ‘b’ y fija la frecuencia de muestreo en 20% para todos los demás servicios: [{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}]
DD_TRACE_RATE_LIMIT
Propiedad en TracerSettings: MaxTracesSubmittedPerSecond
El número de trazas que se permite enviar por segundo (deja obsoleto a DD_MAX_TRACES_PER_SECOND).
Predeterminado: 100 cuando DD_TRACE_SAMPLE_RATE está establecido. En caso contrario, delega el límite de frecuencia al Datadog Agent.
DD_SPAN_SAMPLING_RULES
Predeterminado: null
Una matriz de objetos JSON. Las reglas se aplican en el orden configurado para determinar la frecuencia de muestreo del tramo. El valor de sample_rate debe estar comprendido entre 0,0 y 1,0 (ambos inclusive). Para más información, consulta Mecanismos de ingesta.
Ejemplo: Establece la frecuencia de muestreo del tramo en un 50% para el servicio my-service y el nombre de operación http.request, hasta 50 trazas por segundo: [{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}]
DD_TRACE_DEBUG
activa o desactiva el registro de depuración. Los valores válidos son true o false.
Por defecto: false
DD_TRACE_HEADER_TAGS
Propiedad en TracerSettings:HeaderTags
Acepta un mapa de claves de encabezado sin distinción entre mayúsculas y minúsculas a nombres de etiqueta, y aplica automáticamente los valores de encabezado coincidentes como etiquetas en trazas. También acepta entradas sin un nombre de etiqueta especificado que se asignan automáticamente a etiquetas de la forma http.request.headers.<header-name> y http.response.headers.<header-name>, respectivamente.

Ejemplo (con nombres de etiqueta especificados): User-ID:userId
Si la Request (Solicitud) tiene un encabezado User-ID, su valor se aplica como etiqueta userId a los tramos que produce el servicio.

Ejemplo (sin nombres de etiqueta especificados): User-ID
Si la Request (Solicitud) tiene un encabezado User-ID, su valor se aplica como etiqueta http.request.headers.User-ID .
Si la Answer (Respuesta) tiene un encabezado User-ID, su valor se aplica como etiqueta http.response.headers.User-ID .

Añadido en la versión 1.18.3.
Compatibilidad con encabezados de respuesta y entradas sin nombres de etiqueta añadidos en la versión 1.26.0.
Fase beta: a partir de la versión 2.35.0, si la configuración remota del Agent está habilitada donde se ejecuta este servicio, puedes establecer DD_TRACE_HEADER_TAGS en la interfaz de usuario del Catálogo de servicios.
DD_TRACE_CLIENT_IP_ENABLED
permite recopilar la IP del cliente a partir de los encabezados de IP relevantes.
Añadido en la versión 2.19.0.
Predeterminado: false
DD_TRACE_CLIENT_IP_HEADER
el encabezado IP que se utilizará para la recopilación de IP del cliente, por ejemplo: x-forwarded-for.
Añadido en la versión 2.19.0.
Predeterminado: Datadog analiza lo siguiente: x-forwarded-for, x-real-ip, true-client-ip, x-client-ip, x-forwarded, forwarded-for, x-cluster-client-ip, fastly-client-ip, cf-connecting-ip, cf-connecting-ipv6. Si hay varios, se utilizará el primero de la lista que analice correctamente.
DD_TAGS
Propiedad en TracerSettings: GlobalTags
Si se especifica, añade todas las etiquetas especificadas a todos los tramos generados.
Ejemplo: layer:api, team:intake, key:value
Nota: El delimitador es una coma y un espacio: , .
Añadido en la versión 1.17.0.
DD_TRACE_LOG_DIRECTORY
establece el directorio para logs del rastreador de .NET.
Predeterminado: %ProgramData%\Datadog .NET Tracer\logs\ en Windows, /var/log/datadog/dotnet en Linux
DD_TRACE_LOGFILE_RETENTION_DAYS
durante el inicio del rastreador, esta configuración utiliza el directorio de log actual del rastreador para borrar los archivos log de la misma antigüedad y más antiguos que el número de días dado. Añadido en la versión 2.19.0.
Predeterminado: 31
DD_TRACE_LOGGING_RATE
establece un límite de frecuencia para los mensajes de log. Si se establece, las líneas de log únicas se escriben una vez cada x segundos. Por ejemplo, para loguear un mensaje determinado una vez cada 60 segundos, establece 60. Si estableces 0, se desactiva la limitación de frecuencia de log. Añadido en la versión 1.24.0. Desactivado por defecto.
DD_TRACE_SERVICE_MAPPING
renombra servicios mediante la configuración. Acepta una lista separada por comas de pares clave-valor de las claves de nombre de servicio a renombrar, y el nombre a utilizar en su lugar, en el formato [from-key]:[to-name].
Ejemplo: mysql:main-mysql-db, mongodb:offsite-mongodb-service
El valor from-key es específico del tipo de integración, y debe excluir el prefijo del nombre de la aplicación. Por ejemplo, para cambiar el nombre de my-application-sql-server a main-db, utiliza sql-server:main-db. Añadido en la versión 1.23.0
DD_HTTP_SERVER_TAG_QUERY_STRING
cuando se establece en true, la http.url incluye parámetros de cadena de consulta. Puedes encontrar más detalles en Redactar la consulta en la URL. Predeterminado: true
DD_HTTP_SERVER_TAG_QUERY_STRING_SIZE
cuando DD_HTTP_SERVER_TAG_QUERY_STRING es verdadero, se establece el tamaño máximo de la cadena de consulta a informar, antes del enmascaramiento. Establece 0 para no limitar el tamaño
Predeterminado: 5000
DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
cuando DD_HTTP_SERVER_TAG_QUERY_STRING es true, esta expresión regular redacta los datos confidenciales de la cadena de consulta de las solicitudes entrantes que aparecen en la etiqueta http.url (las coincidencias se sustituyen por <redacted>). Esta expresión regular se ejecuta para cada solicitud entrante.
DD_INSTRUMENTATION_TELEMETRY_ENABLED
Datadog puede recopilar información de entorno y de diagnóstico sobre tu sistema para mejorar el producto. Si es false, no se recopilarán estos datos de telemetría.
Predeterminado: true
DD_TRACE_OTEL_ENABLED
activa o desactiva el rastreo basado en OpenTelemetry, tanto para la instrumentación personalizada como para la automática. Los valores válidos son: true o false.
Predeterminado: false

Configuración opcional de instrumentación automática

Las siguientes variables de configuración están disponibles solo cuando se utiliza la instrumentación automática:

DD_TRACE_ENABLED
Propiedad en TracerSettings: TraceEnabled
Activa o desactiva toda la instrumentación. Los valores válidos son: true o false.
Predeterminado: true Nota: Establecer la variable de entorno en false deshabilita completamente la biblioteca del cliente, y no puede ser habilitada a través de otros métodos de configuración. Si se establece en false a través de otro método de configuración (no una variable de entorno), la biblioteca del cliente se sigue cargando, pero no se generarán trazas.
DD_DBM_PROPAGATION_MODE
permite la conexión entre los datos enviados desde APM y el producto de Database Monitoring cuando se establece en service o full. La opción service permite la conexión entre DBM y servicios de APM. La opción full permite la conexión entre los tramos de base de datos y los eventos de consulta de base de datos. Disponible para Postgres y MySQL.
Predeterminado: disabled
DD_HTTP_CLIENT_ERROR_STATUSES
establece los rangos de códigos de estado que harán que los tramos de cliente HTTP se marquen como error.
Predeterminado: 400-499
DD_HTTP_SERVER_ERROR_STATUSES
establece los rangos de códigos de estado que harán que los tramos de servidor HTTP se marquen como error.
Predeterminado: 500-599
DD_LOGS_INJECTION
Propiedad en TracerSettings: LogsInjectionEnabled
Activa o desactiva la inyección automática de identificadores de correlación en los logs de aplicación.
Tu registrador necesita tener una source que establezca la asignación de trace_id correctamente. La fuente por defecto para aplicaciones .NET, csharp, hace esto automáticamente. Para obtener más información, consulta logs correlacionados en el panel de identificadores de traza.

Fase beta: a partir de la versión 2.35.0, si la configuración remota del Agent está habilitada donde se ejecuta este servicio, puedes establecer DD_LOGS_INJECTION en la interfaz de usuario del Catálogo de servicios.
DD_RUNTIME_METRICS_ENABLED
activa las métricas de tiempo de ejecución de .NET. Los valores válidos son true o false.
Predeterminado: false
Añadido en la versión 1.23.0.
DD_TRACE_EXPAND_ROUTE_TEMPLATES_ENABLED
expande todos los parámetros de ruta en la aplicación para ASP.NET/ASP.NET Core (excepto los parámetros de ID).
Esto puede ser útil si estás utilizando nombres de parámetro para diferenciar entre valores de formulario, o un slug, como en GraphQL. Predeterminado: false Añadido en la versión 2.5.1.
DD_TRACE_METHODS
lista de métodos a rastrear. Acepta una lista separada por punto y coma (;) donde cada entrada tiene el formato Namespace.TypeName[MethodNames], donde MethodNames es una lista separada por comas (,) de los nombres de métodos o el comodín *. Para los tipos genéricos, sustituye los corchetes angulares y los nombres de los parámetros de tipo por un apóstrofo (`) followed by the number of generic type parameters. For example, Dictionary<TKey, TValue> must be written as Dictionary`2. Para los métodos genéricos, solo es necesario especificar el nombre del método.
**Ejemplo Namespace1.Class1[Method1,GenericMethod];Namespace1.GenericTypeWithOneTypeVariable`1[ExecuteAsync];Namespace2.Class2[*]
Nota: El soporte del método de comodín ([*]) selecciona todos los métodos de un tipo excepto constructores, getters y setters de propiedades, Equals, Finalize, GetHashCode y ToString.
Añadido en la versión 2.6.0. Soporte de comodines [*] añadido en la versión 2.7.0.
DD_TRACE_KAFKA_CREATE_CONSUMER_SCOPE_ENABLED
altera el comportamiento del tramo del consumidor de Kafka
Predeterminado: true
Cuando se establece en true, el consumidor de tramo se crea cuando se consume un mensaje y se cierra antes de consumir el siguiente mensaje. La duración del tramo es representativa del cómputo entre el consumo de un mensaje y el siguiente. Utiliza esta configuración cuando el consumo de mensajes se realice en un bucle.
Cuando se establece en false, el consumidor de tramo se crea cuando se consume un mensaje y se cierra inmediatamente. Utiliza este ajuste cuando un mensaje no se procesa completamente antes de consumir el siguiente, o cuando se consumen varios mensajes a la vez. Cuando se ajusta este parámetro en false, el consumidor de tramos se cierra inmediatamente. Si tienes tramos secundarios para rastrear, debes extraer el contexto manualmente. Lee Extracción e inyección de encabezados para más detalles.

Configuración de la integración de instrumentación automática

La siguiente tabla enumera las variables de configuración que están disponibles solo cuando se utiliza la instrumentación automática y que pueden configurarse para cada integración.

DD_DISABLED_INTEGRATIONS
Propiedad en TracerSettings: DisabledIntegrationNames
Establece una lista de integraciones para desactivar. Todas las otras integraciones permanecen habilitadas. Si no se establece, todas las integraciones están habilitadas. Admite varios valores separados por punto y coma. Los valores válidos son los nombres de integración listados en la sección Integraciones.
DD_TRACE_<INTEGRATION_NAME>_ENABLED
Propiedad en TracerSettings: Integrations[<INTEGRATION_NAME>].Enabled
Habilita o deshabilita una integración específica. Los valores válidos son: true o false. Los nombres de integración están listados en la sección Integraciones.
Predeterminado: true

Características experimentales

Las siguientes variables de configuración corresponden a funciones que están disponibles para su uso, pero que pueden cambiar en futuras versiones.

DD_TRACE_PARTIAL_FLUSH_ENABLED
permite la descarga incremental de trazas de gran tamaño al Datadog Agent, reduciendo la posibilidad de rechazo por parte del Agent. Utilízala solo cuando tengas trazas de mucha antigüedad o trazas con muchos tramos. Los valores válidos son true o false. Añadido en la versión 1.26.0, solo compatible con el Datadog Agent 7.26.0+.
Predeterminado: false

Ajustes obsoletos

DD_TRACE_LOG_PATH
establece la ruta para el archivo de log de la instrumentación automática y determina el directorio de todos los demás archivos de log del rastreador de .NET. Se ignora si se establece DD_TRACE_LOG_DIRECTORY.
DD_TRACE_ROUTE_TEMPLATE_RESOURCE_NAMES_ENABLED
habilita nombres de recursos mejorados para los tramos web cuando se establece en true. Utiliza información de plantilla de ruta cuando está disponible, añade un tramo adicional para integraciones de ASP.NET Core y habilita etiquetas adicionales. Añadido en la versión 1.26.0. Activado por defecto en 2.0.0
Predeterminado: true

Leer más

Más enlaces, artículos y documentación útiles: