IDOT and the OpenTelemetry project

Edit online

The Instana Distribution of OpenTelemetry Collector (IDOT) is built on top of the upstream OpenTelemetry Collector open source project. While the core functions come from the upstream project, IDOT provides several Instana-specific enhancements:

  • Pre-configured components optimized for sending telemetry data to Instana backends
  • Streamlined installation and configuration process

In addition, IDOT maintains a carefully curated subset of components from the community version, focusing on stability and security for enterprise environments.

  • IBM maintains security fixes and patches for IDOT
  • Enterprise-grade support through IBM's support channels
  • Regular security audits and vulnerability management
  • Compatibility testing with Instana's backend services

IDOT maintains compatibility with the OpenTelemetry Protocol (OTLP) standard and provides a streamlined experience for Instana users. The distribution is regularly updated to incorporate improvements from the upstream project and helps ensure reliable integration with Instana's observability platform.

Before you begin, review the system requirements to help ensure a smooth installation experience.

Instana Distribution of OpenTelemetry Collector

Edit online

For Instana to receive the telemetry data that is sent by the vendor-agnostic OpenTelemetry Collector, you must configure the OTLP,gRPC, and HTTP endpoints correctly. The Instana Distribution of OpenTelemetry Collector (IDOT) automates the collector configuration process and ensures that Instana receives the telemetry data by default.

Supported architectures

Edit online

The Instana Distribution of OpenTelemetry Collector supports the following architectures:

OS Architectures
Linux x86-64 (amd64), s390x (IBM Z)

Installing the Instana Distribution of OpenTelemetry Collector

Edit online

To install the Instana Distribution of OpenTelemetry Collector in your Linux environment, complete the following steps:

  1. Download the appropriate installer for your architecture:

    For x86-64 or amd64 systems: 

    curl -Lo instana_otelcol_setup.sh https://github.com/instana/instana-otel-collector/releases/latest/download/instana-otel-collector-installer-latest-linux-amd64.sh
chmod +x instana_otelcol_setup.sh

    For s390x or zLinux systems: 

    curl -Lo instana_otelcol_setup.sh https://github.com/instana/instana-otel-collector/releases/latest/download/instana-otel-collector-installer-latest-linux-s390x.sh
chmod +x instana_otelcol_setup.sh

  2. Run the installation script by using the following command:

    ./instana_otelcol_setup.sh -e <INSTANA_OTEL_ENDPOINT_GRPC> -a <INSTANA_KEY> [-H <INSTANA_OTEL_ENDPOINT_HTTP>] [-m INSTANA_METRICS_ENDPOINT] [-u USE_SUPERVISOR_SERVICE] [<install_path>]

    <INSTANA_OTEL_ENDPOINT_GRPC> # GRPC Endpoint for Instana. Format <ip_address>:<port>
<INSTANA_KEY> # Key for authentication into Instana
<INSTANA_OTEL_ENDPOINT_HTTP> # HTTP Endpoint for Instana. Format <ip_address>:<port>
<INSTANA_METRICS_ENDPOINT> # Endpoint for sending collector metrics to. Format <ip_address>:<port>
<USE_SUPERVISOR_SERVICE> # Set as true by default to enable the collector supervisor feature, false will leave the supervisor disabled.

The INSTANA_OTEL_ENDPOINT_GRPC and INSTANA_KEY parameters are required to run the installer. You can change these parameters later in the config.env file that is located in the install_path/collector/config/config.env. The default path is /opt/instana/collector/config/config.env.

The installation script installs IDOT Collector and initiates the Instana Collector Service (and Supervisor Service, if desired) on your system by using the specified parameters.

Managing the Instana Collector Service

Edit online

The IDOT Collector installation script installs and starts the service by default. You can further manage the Instana Collector Service by running the following commands within the bin directory:

  • Install the service:

    ./instana_collector_service.sh install

  • Uninstall the service:

    ./instana_collector_service.sh uninstall

  • Start the service:

    ./instana_collector_service.sh start

    Or

    service instana-collector start

  • Stop the service:

    ./instana_collector_service.sh stop

    Or

    service instana-collector stop

  • Restart the service:

    ./instana_collector_service.sh restart

    Or

    service instana-collector restart

  • Display the status of the service:

    ./instana_collector_service.sh status

    Or

    service instana-collector status

Managing the Instana Supervisor Service

Edit online

As with the Instana Collector Service, the Instana Supervisor Service is installed and initialized during the IDOT installation process. Managing the Supervisor service is done the same way (seen in the preceding section) as managing the service for the collector by using ./instana_supervisor_service.sh instead of ./instana_collector_service.sh.

Configuring the OpenTelemetry Collector

Edit online

You can configure the Collector according to your business requirements by modifying the /opt/instana/collector/config.yaml file. You can also define and modify the pipelines for telemetry data as required. See the following configuration example to support the data flow for all types of telemetry data:

receivers:
    # Configure OTLP/gRPC endpoint
    otlp:
        protocols:
            grpc:
                endpoint: 0.0.0.0:24317
    # Specifies a file log receiver to include logs from a given path
    filelog:
        include: ["path/to/logs/*.log"]
processors:
    # Set a limit for batch size
    batch:
        send_batch_max_size: 10000
    # Specify a transform processor to add a processed attribute for logs
    transform:
        log_statements:
            - set(log.body, log.attributes["processed"])
exporters:
    # Configure OTLP exporter for telemetry data to be sent to
    otlp:
        endpoint: INSTANA_OTEL_ENDPOINT_GRPC
    headers:
      x-instana-key: INSTANA_KEY
      x-instana-host: INSTANA_HOST
    tls:
      insecure: true
# Assemble the data pipeline from the configured components
services:
    pipelines:
        traces:
            receivers: [otlp]
            processors: [batch]
            exporters: [otlp]
        metrics:
            receivers: [otlp]
            processors: [batch]
            exporters: [otlp]
        logs:
            receivers: [filelog]
            processors: [transform]
            exporters: [otlp]

Connecting to different Instana environments

Edit online

Self-hosted environments

Edit online

Self-hosted environments operate differently from the SaaS environments of Instana. For IDOT, the OTLP exporter must be configured differently.

All OTLP traffic must go through the gateway on port 443, using these subdomains:

  • otlp-grpc.<base_domain> → OTLP/gRPC (4317 equivalent)
  • otlp-http.<base_domain> → OTLP/HTTP (4318 equivalent)

By default, the Instana backend uses a self-signed certificate. If you do not configure the collector with the CA file, you must disable verification; otherwise, the TLS handshake fails.

Example configuration snippet (without certificate verification):

exporters:
  otlp:
    endpoint: https://otlp-grpc.<base_domain>:443
    tls:
      insecure: false
      insecure_skip_verify: true
    headers:
      x-instana-key: <your_instana_key>
      x-instana-host: <your_instana_host>

Check the supervisor configuration. Make sure it's targeting the right endpoint and handling the self-signed certificate correctly.

Installing the Instana Distribution of OpenTelemetry Collector on Kubernetes

Edit online

For Kubernetes environments, IDOT can be deployed as a centralized collector using either Helm charts or YAML manifests. This deployment model allows you to perform the following tasks:

  • Collect telemetry data from multiple applications across your cluster
  • Configure high availability with multiple collector instances
  • Manage the collector configuration through Kubernetes native tools

For detailed instructions on installing and configuring IDOT on Kubernetes, see Installing the Instana Distribution of OpenTelemetry Collector on Kubernetes.

Uninstalling the OpenTelemetry Collector

Edit online

By default, the installation script also adds an uninstallation script under collector/bin in the install_path.

./uninstall.sh

Running this script stops the Instana Collector Service and removes all collector files from the system.