dd-trace/index.d.ts

Datadog APM tracing client for JavaScript

import { ClientRequest, IncomingMessage, OutgoingMessage, ServerResponse } from "http";
import { LookupFunction } from 'net';
import * as opentracing from "./vendor/dist/opentracing";
import * as otel from "@opentelemetry/api";

/**
 * Tracer is the entry-point of the Datadog tracing implementation.
 */
interface Tracer extends opentracing.Tracer {
  /**
   * Add tracer as a named export
   */
  tracer: Tracer;

  /**
   * For compatibility with NodeNext + esModuleInterop: false
   */
  default: Tracer;

  /**
   * Starts and returns a new Span representing a logical unit of work.
   * @param {string} name The name of the operation.
   * @param {tracer.SpanOptions} [options] Options for the newly created span.
   * @returns {Span} A new Span object.
   */
  startSpan (name: string, options?: tracer.SpanOptions): tracer.Span;

  /**
   * Injects the given SpanContext instance for cross-process propagation
   * within `carrier`
   * @param  {SpanContext} spanContext The SpanContext to inject into the
   *         carrier object. As a convenience, a Span instance may be passed
   *         in instead (in which case its .context() is used for the
   *         inject()).
   * @param  {string} format The format of the carrier.
   * @param  {any} carrier The carrier object.
   */
  inject (spanContext: tracer.SpanContext | tracer.Span, format: string, carrier: any): void;

  /**
   * Returns a SpanContext instance extracted from `carrier` in the given
   * `format`.
   * @param  {string} format The format of the carrier.
   * @param  {any} carrier The carrier object.
   * @return {SpanContext}
   *         The extracted SpanContext, or null if no such SpanContext could
   *         be found in `carrier`
   */
  extract (format: string, carrier: any): tracer.SpanContext | null;

  /**
   * Initializes the tracer. This should be called before importing other libraries.
   */
  init (options?: tracer.TracerOptions): this;

  /**
   * Sets the URL for the trace agent. This should only be called _after_
   * init() is called, only in cases where the URL needs to be set after
   * initialization.
   */
  setUrl (url: string): this;

  /**
   * Enable and optionally configure a plugin.
   * @param plugin The name of a built-in plugin.
   * @param config Configuration options. Can also be `false` to disable the plugin.
   */
  use<P extends keyof Plugins> (plugin: P, config?: Plugins[P] | boolean): this;

  /**
   * Returns a reference to the current scope.
   */
  scope (): tracer.Scope;

  /**
   * Instruments a function by automatically creating a span activated on its
   * scope.
   *
   * The span will automatically be finished when one of these conditions is
   * met:
   *
   * * The function returns a promise, in which case the span will finish when
   * the promise is resolved or rejected.
   * * The function takes a callback as its second parameter, in which case the
   * span will finish when that callback is called.
   * * The function doesn't accept a callback and doesn't return a promise, in
   * which case the span will finish at the end of the function execution.
   */
  trace<T> (name: string, fn: (span: tracer.Span) => T): T;
  trace<T> (name: string, fn: (span: tracer.Span, done: (error?: Error) => void) => T): T;
  trace<T> (name: string, options: tracer.TraceOptions & tracer.SpanOptions, fn: (span?: tracer.Span, done?: (error?: Error) => void) => T): T;

  /**
   * Wrap a function to automatically create a span activated on its
   * scope when it's called.
   *
   * The span will automatically be finished when one of these conditions is
   * met:
   *
   * * The function returns a promise, in which case the span will finish when
   * the promise is resolved or rejected.
   * * The function takes a callback as its last parameter, in which case the
   * span will finish when that callback is called.
   * * The function doesn't accept a callback and doesn't return a promise, in
   * which case the span will finish at the end of the function execution.
   */
  wrap<T = (...args: any[]) => any> (name: string, fn: T): T;
  wrap<T = (...args: any[]) => any> (name: string, options: tracer.TraceOptions & tracer.SpanOptions, fn: T): T;
  wrap<T = (...args: any[]) => any> (name: string, options: (...args: any[]) => tracer.TraceOptions & tracer.SpanOptions, fn: T): T;

  /**
   * Returns an HTML string containing <meta> tags that should be included in
   * the <head> of a document to enable correlating the current trace with the
   * RUM view. Otherwise, it is not possible to associate the trace used to
   * generate the initial HTML document with a given RUM view. The resulting
   * HTML document should not be cached as the meta tags are time-sensitive
   * and are associated with a specific user.
   *
   * Note that this feature is currently not supported by the backend and
   * using it will have no effect.
   */
  getRumData (): string;

  /**
   * Links an authenticated user to the current trace.
   * @param {User} user Properties of the authenticated user. Accepts custom fields.
   * @returns {Tracer} The Tracer instance for chaining.
   */
  setUser (user: tracer.User): Tracer;

  appsec: tracer.Appsec;

  /**
   * Profiling API for attaching custom labels to profiler samples.
   */
  profiling: tracer.Profiling;

  TracerProvider: tracer.opentelemetry.TracerProvider;

  dogstatsd: tracer.DogStatsD;

  /**
   * Data Streams manual checkpointer API.
   */
  dataStreamsCheckpointer: tracer.DataStreamsCheckpointer;

  /**
   * LLM Observability SDK
   */
  llmobs: tracer.llmobs.LLMObs;

  /**
   * OpenFeature Provider with Remote Config integration.
   *
   * Extends DatadogNodeServerProvider with Remote Config integration for dynamic flag configuration.
   * Enable with DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED=true.
   *
   * @env DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED
   * @beta This feature is in preview and not ready for production use
   */
  openfeature: tracer.OpenFeatureProvider;

  /**
   * AI Guard SDK
   */
  aiguard: tracer.aiguard.AIGuard;

  /**
   * @experimental
   *
   * Set a baggage item and return the new context.
   *
   * @see https://opentelemetry.io/docs/specs/otel/baggage/api/#set-value
   *
   * ----
   *
   * Provide same functionality as OpenTelemetry Baggage:
   * https://opentelemetry.io/docs/concepts/signals/baggage/
   *
   * Since the equivalent of OTel Context is implicit in dd-trace-js,
   * these APIs act on the currently active baggage
   *
   * Work with storage('baggage'), therefore do not follow the same continuity as other APIs.
   */
  setBaggageItem (key: string, value: string, metadata?: object): Record<string, string>;
  /**
   * @experimental
   *
   * Returns a specific baggage item from the current context.
   *
   * @see https://opentelemetry.io/docs/specs/otel/baggage/api/#get-value
   */
  getBaggageItem (key: string): string | undefined;
  /**
   * @experimental
   *
   * Returns all baggage items from the current context.
   *
   * @see https://opentelemetry.io/docs/specs/otel/baggage/api/#get-all-values
   */
  getAllBaggageItems (): Record<string, string>;
  /**
   * @experimental
   *
   * Removes a specific baggage item from the current context and returns the new context.
   *
   * @see https://opentelemetry.io/docs/specs/otel/baggage/api/#remove-value
   */
  removeBaggageItem (key: string): Record<string, string>;

  /**
   * @experimental
   *
   * Removes all baggage items from the current context and returns the new context.
   *
   * @see https://opentelemetry.io/docs/specs/otel/baggage/api/#remove-all-values
   */
  removeAllBaggageItems (): Record<string, string>;
}

// left out of the namespace, so it
// is doesn't need to be exported for Tracer
/** @hidden */
interface Plugins {
  "aerospike": tracer.plugins.aerospike;
  "ai": tracer.plugins.ai;
  "amqp10": tracer.plugins.amqp10;
  "amqplib": tracer.plugins.amqplib;
  "anthropic": tracer.plugins.anthropic;
  "apollo": tracer.plugins.apollo;
  "avsc": tracer.plugins.avsc;
  "aws-sdk": tracer.plugins.aws_sdk;
  "azure-event-hubs": tracer.plugins.azure_event_hubs;
  "azure-functions": tracer.plugins.azure_functions;
  "azure-service-bus": tracer.plugins.azure_service_bus;
  "azure-durable-functions": tracer.plugins.azure_durable_functions
  "bullmq": tracer.plugins.bullmq;
  "bunyan": tracer.plugins.bunyan;
  "cassandra-driver": tracer.plugins.cassandra_driver;
  "child_process": tracer.plugins.child_process;
  "confluentinc-kafka-javascript": tracer.plugins.confluentinc_kafka_javascript;
  "connect": tracer.plugins.connect;
  "couchbase": tracer.plugins.couchbase;
  "cucumber": tracer.plugins.cucumber;
  "cypress": tracer.plugins.cypress;
  "dns": tracer.plugins.dns;
  "elasticsearch": tracer.plugins.elasticsearch;
  "express": tracer.plugins.express;
  "fastify": tracer.plugins.fastify;
  "fetch": tracer.plugins.fetch;
  "find-my-way": tracer.plugins.find_my_way;
  "fs": tracer.plugins.fs;
  "generic-pool": tracer.plugins.generic_pool;
  "google-cloud-pubsub": tracer.plugins.google_cloud_pubsub;
  "google-cloud-vertexai": tracer.plugins.google_cloud_vertexai;
  "google-genai": tracer.plugins.google_genai;
  "graphql": tracer.plugins.graphql;
  "grpc": tracer.plugins.grpc;
  "hapi": tracer.plugins.hapi;
  "hono": tracer.plugins.hono;
  "http": tracer.plugins.http;
  "http2": tracer.plugins.http2;
  "ioredis": tracer.plugins.ioredis;
  "iovalkey": tracer.plugins.iovalkey;
  "jest": tracer.plugins.jest;
  "kafkajs": tracer.plugins.kafkajs;
  "knex": tracer.plugins.knex;
  "koa": tracer.plugins.koa;
  "langchain": tracer.plugins.langchain;
  "langgraph": tracer.plugins.langgraph;
  "mariadb": tracer.plugins.mariadb;
  "memcached": tracer.plugins.memcached;
  "microgateway-core": tracer.plugins.microgateway_core;
  "mocha": tracer.plugins.mocha;
  "moleculer": tracer.plugins.moleculer;
  "mongodb-core": tracer.plugins.mongodb_core;
  "mongoose": tracer.plugins.mongoose;
  "mysql": tracer.plugins.mysql;
  "mysql2": tracer.plugins.mysql2;
  "net": tracer.plugins.net;
  "next": tracer.plugins.next;
  "nyc": tracer.plugins.nyc;
  "openai": tracer.plugins.openai;
  "opensearch": tracer.plugins.opensearch;
  "oracledb": tracer.plugins.oracledb;
  "playwright": tracer.plugins.playwright;
  "pg": tracer.plugins.pg;
  "pino": tracer.plugins.pino;
  "prisma": tracer.plugins.prisma;
  "protobufjs": tracer.plugins.protobufjs;
  "redis": tracer.plugins.redis;
  "restify": tracer.plugins.restify;
  "rhea": tracer.plugins.rhea;
  "router": tracer.plugins.router;
  "selenium": tracer.plugins.selenium;
  "sharedb": tracer.plugins.sharedb;
  "tedious": tracer.plugins.tedious;
  "undici": tracer.plugins.undici;
  "vitest": tracer.plugins.vitest;
  "web": tracer.plugins.web;
  "winston": tracer.plugins.winston;
  "ws": tracer.plugins.ws;
}

declare namespace tracer {
  export type SpanOptions = Omit<opentracing.SpanOptions, 'childOf'> & {
  /**
   * Set childOf to 'null' to create a root span without a parent, even when a parent span
   * exists in the current async context. If 'undefined' the parent will be inferred from the
   * existing async context.
   */
    childOf?: opentracing.Span | opentracing.SpanContext | null;
    /**
     * Optional name of the integration that crated this span.
     */
    integrationName?: string;
  };
  export { Tracer };

  export interface TraceOptions extends Analyzable {
    /**
     * The resource you are tracing. The resource name must not be longer than
     * 5000 characters.
     */
    resource?: string,

    /**
     * The service you are tracing. The service name must not be longer than
     * 100 characters.
     */
    service?: string,

    /**
     * The type of request.
     */
    type?: string

    /**
     * An array of span links
     */
    links?: { context: SpanContext, attributes?: Object }[]
  }

  /**
   * Span represents a logical unit of work as part of a broader Trace.
   * Examples of span might include remote procedure calls or a in-process
   * function calls to sub-components. A Trace has a single, top-level "root"
   * Span that in turn may have zero or more child Spans, which in turn may
   * have children.
   */
  export interface Span extends opentracing.Span {
    context (): SpanContext;

    /**
     * Causally links another span to the current span
     *
     * @deprecated In favor of addLink(link: { context: SpanContext, attributes?: Object }).
     * This will be removed in the next major version.
     * @param {SpanContext} context The context of the span to link to.
     * @param {Object} attributes An optional key value pair of arbitrary values.
     * @returns {void}
     */
    addLink (context: SpanContext, attributes?: Object): void;

    /**
     * Adds a single link to the span.
     *
     * Links added after the creation will not affect the sampling decision.
     * It is preferred span links be added at span creation.
     *
     * @param link the link to add.
     */
    addLink (link: { context: SpanContext, attributes?: Object }): void;

    /**
     * Adds multiple links to the span.
     *
     * Links added after the creation will not affect the sampling decision.
     * It is preferred span links be added at span creation.
     *
     * @param links the links to add.
     */
    addLinks (links: { context: SpanContext, attributes?: Object }[]): void;
  }

  /**
   * SpanContext represents Span state that must propagate to descendant Spans
   * and across process boundaries.
   *
   * SpanContext is logically divided into two pieces: the user-level "Baggage"
   * (see setBaggageItem and getBaggageItem) that propagates across Span
   * boundaries and any Tracer-implementation-specific fields that are needed to
   * identify or otherwise contextualize the associated Span instance (e.g., a
   * <trace_id, span_id, sampled> tuple).
   */
  export interface SpanContext extends opentracing.SpanContext {
    /**
     * Returns the string representation of the internal trace ID.
     */
    toTraceId (): string;

    /**
     * Returns the string representation of the internal span ID.
     */
    toSpanId (): string;

    /**
     * Returns the string representation used for DBM integration.
     */
    toTraceparent (): string;
  }

  /**
   * Sampling rule to configure on the priority sampler.
   */
  export interface SamplingRule {
    /**
     * Sampling rate for this rule.
     */
    sampleRate: number

    /**
     * Service on which to apply this rule. The rule will apply to all services if not provided.
     */
    service?: string | RegExp

    /**
     * Operation name on which to apply this rule. The rule will apply to all operation names if not provided.
     */
    name?: string | RegExp
  }

  /**
   * Span sampling rules to ingest single spans where the enclosing trace is dropped
   */
  export interface SpanSamplingRule {
    /**
     * Sampling rate for this rule. Will default to 1.0 (always) if not provided.
     */
    sampleRate?: number

    /**
     * Maximum number of spans matching a span sampling rule to be allowed per second.
     */
    maxPerSecond?: number

    /**
     * Service name or pattern on which to apply this rule. The rule will apply to all services if not provided.
     */
    service?: string

    /**
     * Operation name or pattern on which to apply this rule. The rule will apply to all operation names if not provided.
     */
    name?: string
  }

  /**
   * Selection and priority order of context propagation injection and extraction mechanisms.
   */
  export interface PropagationStyle {
    /**
     * Selection of context propagation injection mechanisms.
     * @env DD_TRACE_PROPAGATION_STYLE, DD_TRACE_PROPAGATION_STYLE_INJECT
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    inject: string[],

    /**
     * Selection and priority order of context propagation extraction mechanisms.
     * @env DD_TRACE_PROPAGATION_STYLE, DD_TRACE_PROPAGATION_STYLE_EXTRACT
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    extract: string[]
  }

  /**
   * List of options available to the tracer.
   */
  export interface TracerOptions {
    /**
     * Used to disable APM Tracing when using standalone products
     * @default true
     * @env DD_APM_TRACING_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    apmTracingEnabled?: boolean

    /**
     * List of baggage tag keys to be included in the baggage.
     * @default ['user.id', 'session.id', 'account.id']
     * @env DD_TRACE_BAGGAGE_TAG_KEYS
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    baggageTagKeys?: string[];

    /**
     * Whether to enable trace ID injection in log records to be able to correlate
     * traces with logs.
     * @default false
     * @env DD_LOGS_INJECTION
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    logInjection?: boolean,

    /**
     * Whether to enable startup logs.
     * @default false
     * @env DD_TRACE_STARTUP_LOGS
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    startupLogs?: boolean,

    /**
     * The service name to be used for this program. If not set, the service name
     * will attempted to be inferred from package.json
     * @env DD_SERVICE, OTEL_SERVICE_NAME
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    service?: string;

    /**
     * Provide service name mappings for each plugin.
     * @env DD_SERVICE_MAPPING
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    serviceMapping?: { [key: string]: string };

    /**
     * The url of the trace agent that the tracer will submit to.
     * Takes priority over hostname and port, if set.
     * @env DD_TRACE_AGENT_URL
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    url?: string;

    /**
     * The address of the trace agent that the tracer will submit to.
     * @default '127.0.0.1'
     * @env DD_AGENT_HOST
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    hostname?: string;

    /**
     * The port of the trace agent that the tracer will submit to.
     * @default 8126
     * @env DD_TRACE_AGENT_PORT
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    port?: number | string;

    /**
     * Whether to enable profiling.
     * @env DD_PROFILING_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    profiling?: boolean

    /**
     * Options specific for the Dogstatsd agent.
     */
    dogstatsd?: {
      /**
       * The hostname of the Dogstatsd agent that the metrics will submitted to.
       * @env DD_DOGSTATSD_HOST
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      hostname?: string

      /**
       * The port of the Dogstatsd agent that the metrics will submitted to.
       * @default 8125
       * @env DD_DOGSTATSD_PORT
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      port?: number
    };

    /**
     * Set an application’s environment e.g. prod, pre-prod, stage.
     * @env DD_ENV
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    env?: string;

    /**
     * The version number of the application. If not set, the version
     * will attempted to be inferred from package.json.
     * @env DD_VERSION
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    version?: string;

    /**
     * Controls the ingestion sample rate (between 0 and 1) between the agent and the backend.
     * @env DD_TRACE_SAMPLE_RATE
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    sampleRate?: number;

    /**
     * Global rate limit that is applied on the global sample rate and all rules,
     * and controls the ingestion rate limit between the agent and the backend.
     * Defaults to deferring the decision to the agent.
     * @env DD_TRACE_RATE_LIMIT
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    rateLimit?: number,

    /**
     * Sampling rules to apply to priority sampling. Each rule is a JSON,
     * consisting of `service` and `name`, which are regexes to match against
     * a trace's `service` and `name`, and a corresponding `sampleRate`. If not
     * specified, will defer to global sampling rate for all spans.
     * @default []
     * @env DD_TRACE_SAMPLING_RULES
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    samplingRules?: SamplingRule[]

    /**
     * Span sampling rules that take effect when the enclosing trace is dropped, to ingest single spans
     * @default []
     * @env DD_SPAN_SAMPLING_RULES, DD_SPAN_SAMPLING_RULES_FILE
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    spanSamplingRules?: SpanSamplingRule[]

    /**
     * Interval in milliseconds at which the tracer will submit traces to the agent.
     * @default 2000
     * @env DD_TRACE_FLUSH_INTERVAL
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    flushInterval?: number;

    /**
     *  Number of spans before partially exporting a trace. This prevents keeping all the spans in memory for very large traces.
     * @default 1000
     * @env DD_TRACE_PARTIAL_FLUSH_MIN_SPANS
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    flushMinSpans?: number;

    /**
     * Whether to enable runtime metrics, or an object specifying whether to enable specific metric types.
     * @default false
     */
    runtimeMetrics?: boolean | {

       /**
       * @env DD_RUNTIME_METRICS_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      enabled?: boolean,

       /**
       * @env DD_RUNTIME_METRICS_GC_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      gc?: boolean,

       /**
       * @env DD_RUNTIME_METRICS_EVENT_LOOP_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      eventLoop?: boolean,

       /**
       * Whether to use native metrics. When set to false, forces the JS implementation
       * @default true
       * @env DD_RUNTIME_METRICS_NATIVE
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      native?: boolean
    }

    /**
     * Whether to add an auto-generated `runtime-id` tag to metrics.
     * @default false
     * @env DD_RUNTIME_METRICS_RUNTIME_ID_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    runtimeMetricsRuntimeId?: boolean

    /**
     * Custom function for DNS lookups when sending requests to the agent.
     * @default dns.lookup()
     */
    lookup?: LookupFunction

    /**
     * Protocol version to use for requests to the agent. The version configured must be supported by the agent version installed or all traces will be dropped.
     * @default 0.4
     * @env DD_TRACE_AGENT_PROTOCOL_VERSION
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    protocolVersion?: string

    /**
     * Deprecated in favor of the global versions of the variables provided under this option
     *
     * @deprecated
     * @hidden
     */
    ingestion?: {
      /**
       * Controls the ingestion sample rate (between 0 and 1) between the agent and the backend.
       * @env DD_TRACE_SAMPLE_RATE
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      sampleRate?: number

      /**
       * Controls the ingestion rate limit between the agent and the backend. Defaults to deferring the decision to the agent.
       * @env DD_TRACE_RATE_LIMIT
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      rateLimit?: number
    };

    /**
     * Whether to enable inferred proxy services.
     * @default false
     * @env DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    inferredProxyServicesEnabled?: boolean

    /**
     * The site to use for the trace.
     * @default 'datadoghq.com'
     * @env DD_SITE
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    site?: string;

    /**
     * Experimental features can be enabled individually using key / value pairs.
     * @default {}
     */
    experimental?: {

      /**
       * @default false
       * @env DD_TRACE_EXPERIMENTAL_B3_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      b3?: boolean

      /**
       * Whether to write traces to log output or agentless, rather than send to an agent
       * @env DD_TRACE_EXPERIMENTAL_EXPORTER
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      exporter?: 'log' | 'agent' | 'datadog'

      /**
       * Whether to enable the experimental `getRumData` method.
       * @default false
       * @env DD_TRACE_EXPERIMENTAL_GET_RUM_DATA_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      enableGetRumData?: boolean

      /**
       * Configuration of the IAST. Can be a boolean as an alias to `iast.enabled`.
       * @deprecated Please use the non-experimental `iast` option instead.
       */
      iast?: boolean | IastOptions

      /**
       * Configuration of the AppSec. Can be a boolean as an alias to `appsec.enabled`.
       * @deprecated Please use the non-experimental `appsec` option instead.
       */
      appsec?: boolean | {
        /**
         * Configuration of Standalone ASM mode
         * Deprecated in favor of `apmTracingEnabled`.
         *
         * @deprecated Please use `apmTracingEnabled` instead.
         */
        standalone?: {
          /**
           * Whether to enable Standalone ASM.
           * @default false
           * @env DD_EXPERIMENTAL_APPSEC_STANDALONE_ENABLED
           * Programmatic configuration takes precedence over the environment variables listed above.
           */
          enabled?: boolean
        }
      } | TracerOptions['appsec'],

      aiguard?: {
        /**
         * Set to `true` to enable the SDK.
         * @env DD_AI_GUARD_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        enabled?: boolean,
        /**
         * Whether to request blocking mode when evaluating prompts via auto-instrumentation.
         * When `true`, AI Guard will block requests that violate security policies.
         * When `false`, AI Guard evaluates but never blocks (monitor-only mode).
         * @default true
         * @env DD_AI_GUARD_BLOCK
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        block?: boolean,
        /**
         * URL of the AI Guard REST API.
         * @env DD_AI_GUARD_ENDPOINT
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        endpoint?: string,
        /**
         * Timeout used in calls to the AI Guard REST API in milliseconds (default 5000)
         * @env DD_AI_GUARD_TIMEOUT
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        timeout?: number,
        /**
         * Maximum number of conversational messages allowed to be set in the meta-struct
         * @env DD_AI_GUARD_MAX_MESSAGES_LENGTH
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        maxMessagesLength?: number,
        /**
         * Max size of the content property set in the meta-struct
         * @env DD_AI_GUARD_MAX_CONTENT_SIZE
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        maxContentSize?: number
      }

      /**
       * Configuration for Feature Flagging & Experimentation.
       *
       * @beta This feature is in preview and not ready for production use
       */
      flaggingProvider?: {
        /**
         * Whether to enable the feature flagging provider.
         * Requires Remote Config to be properly configured.
         * Can be configured via DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED environment variable.
         *
         * @default false
         * @env DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        enabled?: boolean
        /**
         * Timeout in milliseconds for OpenFeature provider initialization.
         * If configuration is not received within this time, initialization fails.
         * Can be configured via DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS environment variable.
         *
         * @default 30000
         * @env DD_EXPERIMENTAL_FLAGGING_PROVIDER_INITIALIZATION_TIMEOUT_MS
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        initializationTimeoutMs?: number
      }
    };

    /**
     * Whether to load all built-in plugins.
     * @deprecated To deactivate plugins, use the specific DD_TRACE_<INTEGRATION>_ENABLED environment variables.
     * @default true
     */
    plugins?: boolean;

    /**
     * Custom logger to be used by the tracer (if debug = true),
     * should support error(), warn(), info(), and debug() methods
     * see https://datadog.github.io/dd-trace-js/#custom-logging
     */
    logger?: {
      error: (err: Error | string) => void;
      warn: (message: string) => void;
      info: (message: string) => void;
      debug: (message: string) => void;
    };

    /**
     * Global tags that should be assigned to every span.
     * @env DD_TAGS, OTEL_RESOURCE_ATTRIBUTES
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    tags?: { [key: string]: any };

    /**
     * Whether to report the hostname of the service host. This is used when the agent is deployed on a different host and cannot determine the hostname automatically.
     * @default false
     * @env DD_TRACE_REPORT_HOSTNAME
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    reportHostname?: boolean

    /**
     * A string representing the minimum tracer log level to use when debug logging is enabled
     * @default 'debug'
     * @env DD_TRACE_LOG_LEVEL, OTEL_LOG_LEVEL
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    logLevel?: 'debug' | 'info' | 'warn' | 'error'

    /**
     * Enables DBM to APM link using tag injection.
     * @default 'disabled'
     * @env DD_DBM_PROPAGATION_MODE
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    dbmPropagationMode?: 'disabled' | 'service' | 'full'

    /**
     * Whether to enable Data Streams Monitoring.
     * Can also be enabled via the DD_DATA_STREAMS_ENABLED environment variable.
     * When not provided, the value of DD_DATA_STREAMS_ENABLED is used.
     * @default false
     * @env DD_DATA_STREAMS_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    dsmEnabled?: boolean

    /**
     * Configuration for Database Monitoring (DBM).
     */
    dbm?: {
      /**
       * Controls whether to inject the SQL base hash (propagation hash) in DBM SQL comments.
       * This option requires DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED=true to take effect.
       * The propagation hash enables correlation between traces and database operations.
       * @default false
       * @env DD_DBM_INJECT_SQL_BASEHASH
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      injectSqlBaseHash?: boolean
    }

    /**
     * Configuration of the AppSec protection. Can be a boolean as an alias to `appsec.enabled`.
     */
    appsec?: boolean | {
      /**
       * Whether to enable AppSec.
       * @default false
       * @env DD_APPSEC_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      enabled?: boolean,

      /**
       * Specifies a path to a custom rules file.
       * @env DD_APPSEC_RULES
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      rules?: string,

      /**
       * Controls the maximum amount of traces sampled by AppSec attacks, per second.
       * @default 100
       * @env DD_APPSEC_TRACE_RATE_LIMIT
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      rateLimit?: number,

      /**
       * Controls the maximum amount of time in microseconds the WAF is allowed to run synchronously for.
       * @default 5000
       * @env DD_APPSEC_WAF_TIMEOUT
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      wafTimeout?: number,

      /**
       * Specifies a regex that will redact sensitive data by its key in attack reports.
       * @env DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      obfuscatorKeyRegex?: string,

      /**
       * Specifies a regex that will redact sensitive data by its value in attack reports.
       * @env DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      obfuscatorValueRegex?: string,

      /**
       * Specifies a path to a custom blocking template html file.
       * @env DD_APPSEC_HTTP_BLOCKED_TEMPLATE_HTML
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      blockedTemplateHtml?: string,

      /**
       * Specifies a path to a custom blocking template json file.
       * @env DD_APPSEC_HTTP_BLOCKED_TEMPLATE_JSON
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      blockedTemplateJson?: string,

      /**
       * Specifies a path to a custom blocking template json file for graphql requests
       * @env DD_APPSEC_GRAPHQL_BLOCKED_TEMPLATE_JSON
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      blockedTemplateGraphql?: string,

      /**
       * Controls the automated user event tracking configuration
       */
      eventTracking?: {
        /**
         * Controls the automated user tracking mode for user IDs and logins collections. Possible values:
         * *  'anonymous': will hash user IDs and user logins before collecting them
         * *  'anon': alias for 'anonymous'
         * *  'safe': deprecated alias for 'anonymous'
         *
         * *  'identification': will collect user IDs and logins without redaction
         * *  'ident': alias for 'identification'
         * *  'extended': deprecated alias for 'identification'
         *
         * *  'disabled': will not collect user IDs and logins
         *
         * Unknown values will be considered as 'disabled'
         * @default 'identification'
         * @env DD_APPSEC_AUTO_USER_INSTRUMENTATION_MODE
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        mode?:
          'anonymous' | 'anon' | 'safe' |
          'identification' | 'ident' | 'extended' |
          'disabled'
      },
      /**
       * Configuration for Api Security
       */
      apiSecurity?: {
        /** Whether to enable Api Security.
         * @default true
         * @env DD_API_SECURITY_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        enabled?: boolean,

        /** Whether to enable endpoint collection for API Security.
         * @default true
         * @env DD_API_SECURITY_ENDPOINT_COLLECTION_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        endpointCollectionEnabled?: boolean,

        /** Maximum number of endpoints that can be serialized per message.
         * @default 300
         * @env DD_API_SECURITY_ENDPOINT_COLLECTION_MESSAGE_LIMIT
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        endpointCollectionMessageLimit?: number,
      },
      /**
       * Configuration for RASP
       */
      rasp?: {
        /** Whether to enable RASP.
         * @default false
         * @env DD_APPSEC_RASP_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        enabled?: boolean,

        /** Whether to enable request body collection on RASP event
         * @default false
         *
         * @deprecated Use UI and Remote Configuration to enable extended data collection
         * @env DD_APPSEC_RASP_COLLECT_REQUEST_BODY
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        bodyCollection?: boolean
      },
      /**
       * Configuration for stack trace reporting
       */
      stackTrace?: {
        /** Whether to enable stack trace reporting.
         * @default true
         * @env DD_APPSEC_STACK_TRACE_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        enabled?: boolean,

        /** Specifies the maximum number of stack traces to be reported.
         * @default 2
         * @env DD_APPSEC_MAX_STACK_TRACES
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        maxStackTraces?: number,

        /** Specifies the maximum depth of a stack trace to be reported.
         * @default 32
         * @env DD_APPSEC_MAX_STACK_TRACE_DEPTH
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        maxDepth?: number,
      },
      /**
       * Configuration for extended headers collection tied to security events
       *
       * @deprecated Use UI and Remote Configuration to enable extended data collection
       */
      extendedHeadersCollection?: {
        /** Whether to enable extended headers collection
         * @default false
         *
         * @deprecated Use UI and Remote Configuration to enable extended data collection
         * @env DD_APPSEC_COLLECT_ALL_HEADERS
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        enabled: boolean,

        /** Whether to redact collected headers
         * @default true
         *
         * @deprecated Use UI and Remote Configuration to enable extended data collection
         * @env DD_APPSEC_HEADER_COLLECTION_REDACTION_ENABLED
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        redaction: boolean,

        /** Specifies the maximum number of headers collected.
         * @default 50
         *
         * @deprecated Use UI and Remote Configuration to enable extended data collection
         * @env DD_APPSEC_MAX_COLLECTED_HEADERS
         * Programmatic configuration takes precedence over the environment variables listed above.
         */
        maxHeaders: number,
      }
    }

    /**
     * Configuration for Code Origin for Spans.
     */
    codeOriginForSpans?: {
      /**
       * Whether to enable Code Origin for Spans.
       * @default true
       * @env DD_CODE_ORIGIN_FOR_SPANS_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      enabled?: boolean

      experimental?: {
        exit_spans?: {
          /**
           * Whether to attach code origin data to exit spans.
           * @default false
           * @env DD_CODE_ORIGIN_FOR_SPANS_EXPERIMENTAL_EXIT_SPANS_ENABLED
           * Programmatic configuration takes precedence over the environment variables listed above.
           */
          enabled?: boolean
        }
      }
    }

    /**
     * Configuration of the IAST. Can be a boolean as an alias to `iast.enabled`.
     */
    iast?: boolean | IastOptions

    /**
     * Configuration of ASM Remote Configuration
     */
    remoteConfig?: {
      /**
       * Specifies the remote configuration polling interval in seconds
       * @default 5
       * @env DD_REMOTE_CONFIG_POLL_INTERVAL_SECONDS
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      pollInterval?: number,
    }

    /**
     * Whether to enable client IP collection from relevant IP headers
     * @default false
     * @env DD_TRACE_CLIENT_IP_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    clientIpEnabled?: boolean

    /**
     * Custom header name to source the http.client_ip tag from.
     * @env DD_TRACE_CLIENT_IP_HEADER
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    clientIpHeader?: string,

    /**
     * The selection and priority order of context propagation injection and extraction mechanisms.
     * @env DD_TRACE_PROPAGATION_STYLE, DD_TRACE_PROPAGATION_STYLE_INJECT, DD_TRACE_PROPAGATION_STYLE_EXTRACT
     * Also configurable via OTEL_PROPAGATORS when DD-specific propagation vars are not set.
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    tracePropagationStyle?: string[] | PropagationStyle

    /**
     * Cloud payload report as tags
     */
    cloudPayloadTagging?: {
      /**
       *  Additional JSONPath queries to replace with `redacted` in request payloads
       *  Undefined or invalid JSONPath queries disable the feature for requests.
       * @env DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      request?: string,
      /**
       *  Additional JSONPath queries to replace with `redacted` in response payloads
       *  Undefined or invalid JSONPath queries disable the feature for responses.
       * @env DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      response?: string,
      /**
       *  Maximum depth of payload traversal for tags
       * @env DD_TRACE_CLOUD_PAYLOAD_TAGGING_MAX_DEPTH
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      maxDepth?: number
    }

    /**
     * Configuration enabling LLM Observability. Enablement is superseded by the DD_LLMOBS_ENABLED environment variable.
     * @env DD_LLMOBS_ENABLED
     * The environment variable listed above takes precedence over programmatic configuration.
     */
    llmobs?: llmobs.LLMObsEnableOptions

    /**
     * Configuration for Dynamic Instrumentation (Live Debugging).
     */
    dynamicInstrumentation?: {
      /**
       * Whether to enable Dynamic Instrumentation.
       * @default false
       * @env DD_DYNAMIC_INSTRUMENTATION_ENABLED
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      enabled?: boolean

      /**
       * Path to a custom probes configuration file.
       * @env DD_DYNAMIC_INSTRUMENTATION_PROBE_FILE
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      probeFile?: string

      /**
       * Timeout in milliseconds for capturing variable values.
       * @default 15
       * @env DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      captureTimeoutMs?: number

      /**
       * Interval in seconds between uploads of probe data.
       * @default 1
       * @env DD_DYNAMIC_INSTRUMENTATION_UPLOAD_INTERVAL_SECONDS
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      uploadIntervalSeconds?: number

      /**
       * List of identifier names to redact in captured data.
       * These are added to the built-in default list, which always applies.
       * See {@link https://github.com/DataDog/dd-trace-js/blob/master/packages/dd-trace/src/debugger/devtools_client/snapshot/redaction.js | redaction.js}
       * for the default identifiers.
       * To avoid redacting some of those built-in identifiers, use
       * {@link redactionExcludedIdentifiers}.
       * @default []
       * @env DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      redactedIdentifiers?: string[]

      /**
       * List of identifier names to exclude from redaction.
       * Use this to avoid redacting some of the built-in identifiers (see
       * {@link redactedIdentifiers}).
       * @default []
       * @env DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS
       * Programmatic configuration takes precedence over the environment variables listed above.
       */
      redactionExcludedIdentifiers?: string[]
    }

    /**
     * Maximum size in bytes for serialized baggage items.
     * @default 8192
     * @env DD_TRACE_BAGGAGE_MAX_BYTES
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    baggageMaxBytes?: number

    /**
     * Maximum number of baggage items allowed on a context.
     * @default 64
     * @env DD_TRACE_BAGGAGE_MAX_ITEMS
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    baggageMaxItems?: number

    /**
     * Header tags (key-value pairs comma separated) to extract and attach to spans.
     * TODO: In the next major version, this will become an object.
     * @env DD_TRACE_HEADER_TAGS
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    headerTags?: string[]

    /**
     * Whether to use Datadog legacy baggage extraction and injection behavior.
     * @default false
     * @env DD_TRACE_LEGACY_BAGGAGE_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    legacyBaggageEnabled?: boolean

    /**
     * Whether middleware spans should be created.
     * @default true
     * @env DD_TRACE_MIDDLEWARE_TRACING_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    middlewareTracingEnabled?: boolean

    /**
     * Whether to enable OpenAI log collection.
     * @default false
     * @env DD_OPENAI_LOGS_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    openAiLogsEnabled?: boolean

    /**
     * Peer service name remapping rules.
     * @env DD_TRACE_PEER_SERVICE_MAPPING
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    peerServiceMapping?: { [key: string]: string }

    /**
     * Controls the naming schema version used for spans.
     * @default 'v0'
     * @env DD_TRACE_SPAN_ATTRIBUTE_SCHEMA
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    spanAttributeSchema?: 'v0' | 'v1'

    /**
     * Whether to compute peer.service tags automatically.
     * @default false
     * @env DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    spanComputePeerService?: boolean

    /**
     * Whether to remove integration names from service names under the active schema.
     * @default false
     * @env DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    spanRemoveIntegrationFromService?: boolean

    /**
     * Whether to enable client-side stats computation.
     * @default false
     * @env DD_TRACE_STATS_COMPUTATION_ENABLED
     * Programmatic configuration takes precedence over the environment variables listed above.
     */
    stats?: boolean

    /**
     * Whether to generate 128-bit trace IDs.
     * @default true
     * @env DD_TRACE_128_BIT_TRACEID_GENE