Interface TracerOptions

List of options available to the tracer.

interface TracerOptions {
    appsec?: boolean | {
        apiSecurity?: {
            enabled?: boolean;
        };
        blockedTemplateGraphql?: string;
        blockedTemplateHtml?: string;
        blockedTemplateJson?: string;
        enabled?: boolean;
        eventTracking?: {
            mode?: "disabled" | "anonymous" | "anon" | "safe" | "identification" | "ident" | "extended";
        };
        obfuscatorKeyRegex?: string;
        obfuscatorValueRegex?: string;
        rasp?: {
            enabled?: boolean;
        };
        rateLimit?: number;
        rules?: string;
        stackTrace?: {
            enabled?: boolean;
            maxDepth?: number;
            maxStackTraces?: number;
        };
        wafTimeout?: number;
    };
    clientIpEnabled?: boolean;
    clientIpHeader?: string;
    cloudPayloadTagging?: {
        maxDepth?: number;
        request?: string;
        response?: string;
    };
    dbmPropagationMode?: "full" | "service" | "disabled";
    dogstatsd?: {
        hostname?: string;
        port?: number;
    };
    env?: string;
    experimental?: {
        appsec?: {
            standalone?: {
                enabled?: boolean;
            };
        };
        b3?: boolean;
        enableGetRumData?: boolean;
        exporter?: "log" | "agent" | "datadog";
        iast?: boolean | IastOptions;
        runtimeId?: boolean;
        traceparent?: boolean;
    };
    flushInterval?: number;
    flushMinSpans?: number;
    hostname?: string;
    iast?: boolean | IastOptions;
    llmobs?: LLMObsEnableOptions;
    logInjection?: boolean;
    logLevel?: "error" | "debug";
    logger?: {
        debug: ((message) => void);
        error: ((err) => void);
        info: ((message) => void);
        warn: ((message) => void);
    };
    lookup?: LookupFunction;
    orphanable?: boolean;
    plugins?: boolean;
    port?: string | number;
    profiling?: boolean;
    propagationStyle?: string[] | PropagationStyle;
    protocolVersion?: string;
    rateLimit?: number;
    remoteConfig?: {
        pollInterval?: number;
    };
    reportHostname?: boolean;
    runtimeMetrics?: boolean;
    sampleRate?: number;
    samplingRules?: SamplingRule[];
    scope?: "async_hooks" | "async_local_storage" | "async_resource" | "sync" | "noop";
    service?: string;
    serviceMapping?: {
        [key: string]: string;
    };
    spanSamplingRules?: SpanSamplingRule[];
    startupLogs?: boolean;
    tags?: {
        [key: string]: any;
    };
    url?: string;
    version?: string;
}

Properties

appsec? clientIpEnabled? clientIpHeader? cloudPayloadTagging? dbmPropagationMode? dogstatsd? env? experimental? flushInterval? flushMinSpans? hostname? iast? llmobs? logInjection? logLevel? logger? lookup? orphanable? plugins? port? profiling? propagationStyle? protocolVersion? rateLimit? remoteConfig? reportHostname? runtimeMetrics? sampleRate? samplingRules? scope? service? serviceMapping? spanSamplingRules? startupLogs? tags? url? version?

Properties

Optional appsec

appsec?: boolean | {
    apiSecurity?: {
        enabled?: boolean;
    };
    blockedTemplateGraphql?: string;
    blockedTemplateHtml?: string;
    blockedTemplateJson?: string;
    enabled?: boolean;
    eventTracking?: {
        mode?: "disabled" | "anonymous" | "anon" | "safe" | "identification" | "ident" | "extended";
    };
    obfuscatorKeyRegex?: string;
    obfuscatorValueRegex?: string;
    rasp?: {
        enabled?: boolean;
    };
    rateLimit?: number;
    rules?: string;
    stackTrace?: {
        enabled?: boolean;
        maxDepth?: number;
        maxStackTraces?: number;
    };
    wafTimeout?: number;
}

Configuration of the AppSec protection. Can be a boolean as an alias to appsec.enabled.

Type declaration

  • Optional apiSecurity?: {
        enabled?: boolean;
    }

    Configuration for Api Security

    • Optional enabled?: boolean

      Whether to enable Api Security.

      Default

      true
  • Optional blockedTemplateGraphql?: string

    Specifies a path to a custom blocking template json file for graphql requests

  • Optional blockedTemplateHtml?: string

    Specifies a path to a custom blocking template html file.

  • Optional blockedTemplateJson?: string

    Specifies a path to a custom blocking template json file.

  • Optional enabled?: boolean

    Whether to enable AppSec.

    Default

    false
  • Optional eventTracking?: {
        mode?: "disabled" | "anonymous" | "anon" | "safe" | "identification" | "ident" | "extended";
    }

    Controls the automated user event tracking configuration

    • Optional mode?: "disabled" | "anonymous" | "anon" | "safe" | "identification" | "ident" | "extended"

      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'
  • Optional obfuscatorKeyRegex?: string

    Specifies a regex that will redact sensitive data by its key in attack reports.

  • Optional obfuscatorValueRegex?: string

    Specifies a regex that will redact sensitive data by its value in attack reports.

  • Optional rasp?: {
        enabled?: boolean;
    }

    Configuration for RASP

    • Optional enabled?: boolean

      Whether to enable RASP.

      Default

      false
  • Optional rateLimit?: number

    Controls the maximum amount of traces sampled by AppSec attacks, per second.

    Default

    100
  • Optional rules?: string

    Specifies a path to a custom rules file.

  • Optional stackTrace?: {
        enabled?: boolean;
        maxDepth?: number;
        maxStackTraces?: number;
    }

    Configuration for stack trace reporting

    • Optional enabled?: boolean

      Whether to enable stack trace reporting.

      Default

      true
    • Optional maxDepth?: number

      Specifies the maximum depth of a stack trace to be reported.

      Default

      32
    • Optional maxStackTraces?: number

      Specifies the maximum number of stack traces to be reported.

      Default

      2
  • Optional wafTimeout?: number

    Controls the maximum amount of time in microseconds the WAF is allowed to run synchronously for.

    Default

    5000

Optional clientIpEnabled

clientIpEnabled?: boolean

Whether to enable client IP collection from relevant IP headers

Default

false

Optional clientIpHeader

clientIpHeader?: string

Custom header name to source the http.client_ip tag from.

Optional cloudPayloadTagging

cloudPayloadTagging?: {
    maxDepth?: number;
    request?: string;
    response?: string;
}

Cloud payload report as tags

Type declaration

  • Optional maxDepth?: number

    Maximum depth of payload traversal for tags

  • Optional request?: string

    Additional JSONPath queries to replace with redacted in request payloads Undefined or invalid JSONPath queries disable the feature for requests.

  • Optional response?: string

    Additional JSONPath queries to replace with redacted in response payloads Undefined or invalid JSONPath queries disable the feature for responses.

Optional dbmPropagationMode

dbmPropagationMode?: "full" | "service" | "disabled"

Enables DBM to APM link using tag injection.

Default

'disabled'

Optional dogstatsd

dogstatsd?: {
    hostname?: string;
    port?: number;
}

Options specific for the Dogstatsd agent.

Type declaration

  • Optional hostname?: string

    The hostname of the Dogstatsd agent that the metrics will submitted to.

  • Optional port?: number

    The port of the Dogstatsd agent that the metrics will submitted to.

    Default

    8125

Optional env

env?: string

Set an application’s environment e.g. prod, pre-prod, stage.

Optional experimental

experimental?: {
    appsec?: {
        standalone?: {
            enabled?: boolean;
        };
    };
    b3?: boolean;
    enableGetRumData?: boolean;
    exporter?: "log" | "agent" | "datadog";
    iast?: boolean | IastOptions;
    runtimeId?: boolean;
    traceparent?: boolean;
}

Experimental features can be enabled individually using key / value pairs.

Type declaration

  • Optional appsec?: {
        standalone?: {
            enabled?: boolean;
        };
    }
    • Optional standalone?: {
          enabled?: boolean;
      }

      Configuration of Standalone ASM mode

      • Optional enabled?: boolean

        Whether to enable Standalone ASM.

        Default

        false
  • Optional b3?: boolean
  • Optional enableGetRumData?: boolean

    Whether to enable the experimental getRumData method.

    Default

    false
  • Optional exporter?: "log" | "agent" | "datadog"

    Whether to write traces to log output or agentless, rather than send to an agent

    Default

    false
  • Optional iast?: boolean | IastOptions

    Configuration of the IAST. Can be a boolean as an alias to iast.enabled.

  • Optional runtimeId?: boolean

    Whether to add an auto-generated runtime-id tag to metrics.

    Default

    false
  • Optional traceparent?: boolean

Default

{}

Optional flushInterval

flushInterval?: number

Interval in milliseconds at which the tracer will submit traces to the agent.

Default

2000

Optional flushMinSpans

flushMinSpans?: number

Number of spans before partially exporting a trace. This prevents keeping all the spans in memory for very large traces.

Default

1000

Optional hostname

hostname?: string

The address of the trace agent that the tracer will submit to.

Default

'localhost'

Optional iast

iast?: boolean | IastOptions

Configuration of the IAST. Can be a boolean as an alias to iast.enabled.

Optional llmobs

llmobs?: LLMObsEnableOptions

Configuration enabling LLM Observability. Enablement is superceded by the DD_LLMOBS_ENABLED environment variable.

Optional logInjection

logInjection?: boolean

Whether to enable trace ID injection in log records to be able to correlate traces with logs.

Default

false

Optional logLevel

logLevel?: "error" | "debug"

A string representing the minimum tracer log level to use when debug logging is enabled

Default

'debug'

Optional logger

logger?: {
    debug: ((message) => void);
    error: ((err) => void);
    info: ((message) => void);
    warn: ((message) => void);
}

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

Type declaration

  • debug: ((message) => void)
      • (message): void

      • Parameters

        • message: string

        Returns void

  • error: ((err) => void)
      • (err): void

      • Parameters

        • err: string | Error

        Returns void

  • info: ((message) => void)
      • (message): void

      • Parameters

        • message: string

        Returns void

  • warn: ((message) => void)
      • (message): void

      • Parameters

        • message: string

        Returns void

Optional lookup

lookup?: LookupFunction

Custom function for DNS lookups when sending requests to the agent.

Default

dns.lookup()

Optional orphanable

orphanable?: boolean

If false, require a parent in order to trace.

Default

true

Deprecated

since version 4.0

Optional plugins

plugins?: boolean

Whether to load all built-in plugins.

Default

true

Optional port

port?: string | number

The port of the trace agent that the tracer will submit to.

Default

8126

Optional profiling

profiling?: boolean

Whether to enable profiling.

Optional propagationStyle

propagationStyle?: string[] | PropagationStyle

The selection and priority order of context propagation injection and extraction mechanisms.

Optional protocolVersion

protocolVersion?: string

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

Optional rateLimit

rateLimit?: 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.

Optional remoteConfig

remoteConfig?: {
    pollInterval?: number;
}

Configuration of ASM Remote Configuration

Type declaration

  • Optional pollInterval?: number

    Specifies the remote configuration polling interval in seconds

    Default

    5

Optional reportHostname

reportHostname?: boolean

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

Optional runtimeMetrics

runtimeMetrics?: boolean

Whether to enable runtime metrics.

Default

false

Optional sampleRate

sampleRate?: number

Controls the ingestion sample rate (between 0 and 1) between the agent and the backend.

Optional samplingRules

samplingRules?: SamplingRule[]

Sampling rules to apply to priority samplin. 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

[]

Optional scope

scope?: "async_hooks" | "async_local_storage" | "async_resource" | "sync" | "noop"

Specifies which scope implementation to use. The default is to use the best implementation for the runtime. Only change this if you know what you are doing.

Optional service

service?: string

The service name to be used for this program. If not set, the service name will attempted to be inferred from package.json

Optional serviceMapping

serviceMapping?: {
    [key: string]: string;
}

Provide service name mappings for each plugin.

Type declaration

  • [key: string]: string

Optional spanSamplingRules

spanSamplingRules?: SpanSamplingRule[]

Span sampling rules that take effect when the enclosing trace is dropped, to ingest single spans

Default

[]

Optional startupLogs

startupLogs?: boolean

Whether to enable startup logs.

Default

true

Optional tags

tags?: {
    [key: string]: any;
}

Global tags that should be assigned to every span.

Type declaration

  • [key: string]: any

Optional url

url?: string

The url of the trace agent that the tracer will submit to. Takes priority over hostname and port, if set.

Optional version

version?: string

The version number of the application. If not set, the version will attempted to be inferred from package.json.

Settings

Member Visibility

Theme

On This Page

appsecclientIpEnabledclientIpHeadercloudPayloadTaggingdbmPropagationModedogstatsdenvexperimentalflushIntervalflushMinSpanshostnameiastllmobslogInjectionlogLevelloggerlookuporphanablepluginsportprofilingpropagationStyleprotocolVersionrateLimitremoteConfigreportHostnameruntimeMetricssampleRatesamplingRulesscopeserviceserviceMappingspanSamplingRulesstartupLogstagsurlversion