Configuring the Node.js collector

The collector tries to communicate with the Instana agent via IP 127.0.0.1 and as a fallback via the host's default gateway. Should the agent not be available under either of these IPs, you can use the agentHost option to use a custom IP.

require('@instana/collector')({
  agentHost: '::1' // use IPv6 to contact via localhost
});
 

Or leverage an environment variable.

require('@instana/collector')({
  agentHost: process.env.HOST_IP
});
 

If not configured, the Instana collector will look for an environment variable called INSTANA_AGENT_HOST and use what is defined in this environment variable to communicate with the agent. If there is no such environment variable, it will try to contact the agent first on localhost and then on the default gateway.

The collector tries to communicate with the Instana Agent via port 42699. Should the port have been changed, you can use the agentPort option to change the port.

require('@instana/collector')({
  agentPort: 42699
});
 

If not configured, the Instana collector will look for an environment variable called INSTANA_AGENT_PORT and use what is defined in this environment variable to communicate with the agent. If there is no such environment variable, it will fall back to the default port 42699.

If your Node.js application and the Instana agent run in a Kubernetes cluster, check the documentation on Kubernetes network access for information about the required configuration in this setup.

In non-serverless environments with an Instana agent, the Node.js Tracer triggers issue events when it detects that the running Node.js version has reached end of life (EOL).

To suppress these EOL events, you can disable them using the following environment variable:

INSTANA_TRACING_DISABLE_EOL_EVENTS=true
 

For a complete list of EOL Node.js versions, refer to the official Node.js releases page.

By default, the Instana Node.js Tracer captures only exit spans with an active entry span. You can enable this feature to allow the tracer to trace standalone exit spans.

To enable this feature, use any one of the following options:

• Set the INSTANA_ALLOW_ROOT_EXIT_SPAN environment variable.

• Configure the feature through the Tracer initialization function:

  require('@instana/collector')({
  tracing: {
    allowRootExitSpan: true
  }
  });
   

If INSTANA_ALLOW_ROOT_EXIT_SPAN is configured to 1 or true, or if allowRootExitSpan is set to true, the tracer captures exit spans even in the absence of active entry span.

This feature is useful for the following scenarios where tasks are triggered by a mechanism, which is not supported by Instana automatic instrumentation:

• Incoming messages from unsupported messaging libraries
• Requests that are made through unsupported protocols, like raw Transmission Control Protocol (TCP) or WebSocket
• Scheduled jobs that are initiated internally by the application by using mechanisms, such as setTimeout, setInterval, or unsupported Node.js scheduling libraries

Starting from Node.js Tracer 4.9.0, you can reduce unnecessary data ingestion by excluding specific traces or calls. This filtering mechanism refines your trace collection. To exclude traces, define these parameters in the Node.js Tracer configuration settings:

• Technology: Specify the relevant technology, for example, Kafka, Redis, DynamoDB, or HTTP.
• Method: Identify the method to be excluded. For example, exclude these methods for the following technologies:
  • Kafka: send, consume
  • Redis: get, type
  • DynamoDB: query, scan
  • HTTP: get, post
• Endpoint (if applicable): Further refine filtering based on specific endpoints. For example, the endpoints for the following technologies are defined as:
  • Kafka: The endpoint is the topic name.
  • HTTP: The endpoint is the URL path.
• Connection (Optional): Exclude traces for a specific connection. For example, the connection for the following technologies is defined as:
  • Redis: The connection is the connection string.
  • HTTP: The connection includes the host and port.

To disable tracing, you can either turn it off completely or selectively exclude specific instrumentations or entire groups, such as databases, messaging, or logging. This flexibility allows you to fine-tune tracing based on the needs of your application.

To apply the configuration to disable tracing, use any one of the following methods:

• Environment variables
• In-code configuration
• Agent configuration (YAML)

Automatic tracing is also enabled by default. To disable only automatic tracing (leaving manual tracing via the SDK or openTracing enabled), pass the following option to the initialization function:

require('@instana/collector')({
  tracing: {
    automaticTracingEnabled: false
  }
});
 

Finally, you can disable automatic tracing by setting the environment variable INSTANA_DISABLE_AUTO_INSTR=true.

When automatic tracing is disabled, you can still use the SDK or the OpenTracing API to create spans manually.

The Opentelemetry integration is enabled by default. To disable the integration, pass the following option to the initialization function:

require('@instana/collector')({
  tracing: {
    useOpentelemetry: false
  }
});
 

Moreover, you can disable the OpenTelemetry integration by setting the INSTANA_DISABLE_USE_OPENTELEMETRY variable to true. For more information, see Instana environment variables.

To prevent the Instana Node.js collector from tracing worker threads, set the following environment variable:

INSTANA_DISABLE_WORKER_THREADS=true

This configuration disables tracing for all worker threads but the main process is still traced automatically. Use this configuration when worker threads run internal or background tasks that you want excluded from tracing.

By default, the collector captures the last ten call sites for every captured exit span. This value can be increased and decreased as necessary. (Note that the stack traces of HTTP entry spans are not collected – they would only show Node.js core code.) Use a value of 0 to disable stack trace capturing.

require('@instana/collector')({
  tracing: {
    stackTraceLength: 10
  }
});
 

You can also configure the stack trace length by setting the environment variable INSTANA_STACK_TRACE_LENGTH.

The Instana collector attempts to locate the primary package.json file within your project to extract important information like your application's name. If you need to define a custom path for your package.json file or if the collector is unable to locate the file, then you can use the configuration option named packageJsonPath.

require('@instana/collector')({
  packageJsonPath: 'absolute/path/to/package.json'
});
 

You can also configure the path for the package.json file by setting the INSTANA_PACKAGE_JSON_PATH environment variable.

Services are a central concept within Instana. Calls, spans and traces are closely associated to services. By default, the Node.js collector will use the name and version attribute from the main package.json file. To customize the service name, you can configure the serviceName property.

require('@instana/collector')({
  serviceName: 'shop'
});
 

You can also configure a custom service name by setting the environment variable INSTANA_SERVICE_NAME. For more information about configuring a custom service, see Setting the service name globally.

Starting from collector version 4.x, Kafka trace correlation headers are always sent in the string format, eliminating support for binary format. For more information, see Kafka header migration.

Remove any configurations that reference the environment variable INSTANA_KAFKA_HEADER_FORMAT and the in-code configuration option tracing: { kafka: { headerFormat: .... }}}.

If you want to change the default log level, you can configure that via:

require('@instana/collector')({
  level: 'debug'
});
 

You can also configure the log level by setting the environment variable INSTANA_LOG_LEVEL to either debug, info, warn or error. Finally, setting INSTANA_DEBUG to any non-empty string will set the log level to debug.

Please note that the default log level is info. If you see unexpected Instana-related debug logs (log lines including "name":"@instana/collector" and "level":20) check if you have set the log level to debug in your configuration or if INSTANA_LOG_LEVEL=debug or INSTANA_DEBUG is set. If you provide your own logger (see as follows) you are responsible for setting the log level on it as desired.

See setting the logger.