Node.js Collector Configuration

Agent Host

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.

Agent Port

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.

Kubernetes & OpenShift

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.

Disabling Automatic Tracing

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.

Disabling OpenTelemetry integration

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.

Capturing Stack Traces

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.

Configuring a custom package.json path

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.

Disabling Individual Tracers

Since: 1.80.0

You can disable individual tracing instrumentations. This should only be used in special circumstances or for troubleshooting.

require('@instana/collector')({
  tracing: {
    disabledTracers: ['graphql', 'grpc']
  }
});

Alternatively, this can be archived by setting the environment variable INSTANA_DISABLED_TRACERS to a comma separated list of tracers you want to disable:

INSTANA_DISABLED_TRACERS=graphql,grpc

Possible values (case insensitive):

• aws-sdk/v2: Disables all instrumentations of the aws-sdk package.
• aws-sdk/v3: Disables all instrumentations of the @aws-sdk/* packages.
• amqp: Disables instrumentation of the amqplib package for RabbitMQ/amqp tracing.
• bluebird: Disables instrumentation of the bluebird package.
• bunyan: Disables instrumentation of the bunyan package for Bunyan warn/error log message collection.
• bull: Disables instrumentation of the bull package.
• console: Disables instrumentation of the core module console.
• couchbase: Disables instrumentation of the couchbase package for Couchbase tracing.
• db2: Disables instrumentation of the ibm_db package for IBM DB2 tracing.
• elasticsearchLegacy: Disables instrumentation of the elasticsearch package for Elasticsearch tracing (legacy client).
• elasticsearchModern: Disables instrumentation of the @elastic/elasticsearch package for Elasticsearch tracing (modern client).
• express: Disables instrumentation of the express package for Express path template collection.
• fastify: Disables instrumentation of the fastify package for Fastify path template collection.
• gcp/pubsub: Disables instrumentation of the @google-cloud/pubsub package.
• gcp/storage: Disables instrumentation of the @google-cloud/storage package.
• graphql: Disables instrumentation of the packages graphql and @apollo\/gateway for GraphQL tracing.
• graphqlSubscriptions: Disables instrumentation of the package graphql-subscriptions.
• grpc: Disables instrumentation of the grpc package for gRPC tracing.
• grpcJs: Disables instrumentation of the @grpc/grpc-js package for JavaScript gRPC tracing.
• hapi: Disables instrumentation of the @hapi/call package for path template collection for Hapi.
• httpClient: Disables instrumentation of the core http and https modules for tracing of outgoing HTTP(S) calls (exits).
• http2Client: Disables instrumentation of the core module http2 for tracing of outgoing HTTP(S) calls (exits).
• httpServer: Disables instrumentation of the core http and https modules for tracing of incoming HTTP(S) calls (entries).
• http2Server: Disables instrumentation of the core module http2 for tracing of incoming HTTP(S) calls (entries).
• ioredis: Disables instrumentation of the ioredis package for Redis tracing (also see option redis).
• kafkaJs: Disables instrumentation of the kafkajs package for Kafka tracing (also see option kafkaNode).
• kafkaNode: Disables instrumentation of the kafka-node package for Kafka tracing (also see option kafaJs).
• koa: Disables instrumentation of the koa-router package for Koa path template collection.
• log4js: Disables instrumentation of the log4js package for warn/error log message collection.
• memcached: Disables instrumentation of the memcached package.
• mongodb: Disables instrumentation of the mongodb/mongodb-core package for MongoDB tracing.
• mongoose: Disables instrumentation of the mongoose package.
• mssql: Disables instrumentation of the mssql package for MSSQL tracing.
• mysql: Disables instrumentation of the mysql and `mysql2' packages for MySQL tracing.
• nativeFetch: Disables instrumentation of the core module fetch.
• nats: Disables instrumentation of the nats package for NATS (but not NATS streaming) tracing (also see option natsStreaming).
• natsStreaming: Disables instrumentation of the node-nats-streaming package for NATS streaming (but not NATS) tracing (also see option nats).
• pgNative: Disables instrumentation of the pg-native package for PostgreSQL tracing (also see option (pg).
• pg: Disables instrumentation of the pg package for PostgreSQL tracing (also see option pgNative).
• pino: Disables instrumentation of the pino package for warn/error log message collection.
• prisma: Disables instrumentation of the @prisma/client package.
• rdkafka: Disables instrumentation of the node-rdkafka package.
• redis: Disables instrumentation of the redis package for Redis tracing (also see option ioredis).
• superagent: Disables instrumentation of the superagent package.
• winston: Disables instrumentation of the winston package for warn/error log message collection.

Service Naming

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.

Kafka Trace Correlation Headers

You can configure the format for Kafka trace correlation headers that are used by the Node.js tracer with the environment variable INSTANA_KAFKA_HEADER_FORMAT. Valid values are binary, string, or both. You can also disable Kafka trace correlation entirely with INSTANA_KAFKA_TRACE_CORRELATION=false, but this is not recommended.

Both options can also be configured in the application code as follows:

require('@instana/collector')({
  tracing: {
    kafka: {
      // valid options: 'binary', 'string', or 'both'
      headerFormat: 'string',
      // valid options: true or false
      traceCorrelation: true
    }
  }
});

Another alternative is to configure the Kafka trace correlation options at the level of the Instana host agent.

For more information, see Kafka Header Migration.

Log Level Configuration

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 as shown above 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.

Custom (Parent) Logger

See setting the logger.