IDOT and the OpenTelemetry project

To install the IDOT in your target 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
    

   For AIX systems:

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

   Note:

   The Instana UI provides a simplified installation script (instana-collector-installer-latest.sh) that automatically detects your system architecture. Both the UI script and the architecture-specific scripts install the same collector.

   For Windows (one-liner download and installation)

   powershell -Command "Invoke-WebRequest -Uri 'https://github.com/instana/instana-otel-collector/releases/download/<latest-version>/instana-otel-collector-installer-latest-windows-amd64.zip' -OutFile '$env:TEMP\instana-collector.zip'; Expand-Archive -Path '$env:TEMP\instana-collector.zip' -DestinationPath 'C:\Program Files\Instana\' -Force; Set-Location 'C:\Program Files\Instana\instana-collector\bin'; .\setenv.bat -a <INSTANA_KEY> -e <INSTANA_OTEL_ENDPOINT_GRPC> -H <INSTANA_OTEL_ENDPOINT_HTTP>; .\start.bat"

   For Windows (MSI installation)

   Use the MSI installer as the recommended installation method for Windows environments. The MSI installer supports interactive GUI installation, automatically registers a Windows service, and integrates with enterprise deployment tools such as Group Policy and SCCM.

   For more information, see Installing IDOT on Windows by using the MSI installer.

   For Kubernetes Helm chart

   helm install instana-otel-collector \
     --repo https://instana.github.io/instana-otel-collector instana-otel-collector-chart \
     --namespace instana-otel-collector \
     --create-namespace \
     --set clusterName=<CLUSTER_NAME> \
     --set instanaEndpoint=<INSTANA_OTEL_ENDPOINT> \
     --set instanaKey=<INSTANA_KEY>

   For more information about Kubernetes installation guidelines, including the operator and OpenShift OS support, see Installing the Instana Distribution of OpenTelemetry Collector on Kubernetes.

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

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

   Use the following parameters with the installation script:

   • <INSTANA_OTEL_ENDPOINT_GRPC>: Specifies the required gRPC endpoint for Instana. Use the <ip_address>:<port> format.
   • <INSTANA_KEY>: Specifies the required Instana agent key for authentication.
   • <INSTANA_OTEL_ENDPOINT_HTTP>: Specifies the optional HTTP endpoint for Instana. Use the <ip_address>:<port> format.
   • <USE_SUPERVISOR_SERVICE>: Specifies whether the Instana Supervisor Service is enabled. The default value is true. Set this parameter to false to disable the supervisor service.
   Important:

   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. In addition, root access is required for installing, as the collector typically needs to write to system directories and configure system-level services.

For more information about OpenTelemetry terminology such as the Supervisor Service and Collector Service, see the OpenTelemetry Collector Management documentation.

The shell receiver supports the following configuration options:

receivers:
  shell:
    collection_interval: 60s  # How often to execute commands (default: 60s)
    commands:
      - name: disk_usage       # Required: Unique identifier for this command
        command: df -h /       # Required: Shell command to execute
        shell: /bin/sh         # Optional: Shell to use (default: /bin/sh)
        args: []               # Optional: Additional arguments to pass to the shell
        timeout: 5s            # Optional: Maximum time the command can run
        metric_name: disk.usage # Required for metrics: Name for the metric
        log_name: disk_check   # Optional: Name for log records (defaults to metric_name)
        description: "Check disk usage" # Optional: Human-readable description
        labels:                # Optional: Additional key-value pairs as attributes
          filesystem: "root"
        output_type: both      # Optional: How to process output (metric, log, or both; default: metric)

Each command in the commands list supports the following options:

The receiver supports the following parsing modes:

The following examples show the different configuration options:

receivers:
  shell:
    collection_interval: 30s
    commands:
      - name: cpu_temperature
        command: cat /sys/class/thermal/thermal_zone0/temp
        metric_name: system.cpu.temperature
        description: "CPU temperature in millidegrees Celsius"

receivers:
  shell:
    collection_interval: 60s
    commands:
      - name: memory_free
        command: free -m | grep Mem | awk '{print $4}'
        metric_name: system.memory.free
        description: "Free memory in MB"
        labels:
          unit: "MB"
        output_type: metric

      - name: disk_usage
        command: df -h / | grep / | awk '{print $5}' | sed 's/%//'
        metric_name: system.disk.usage
        description: "Root filesystem usage percentage"
        labels:
          filesystem: "root"
          unit: "percent"
        output_type: both

      - name: last_logins
        command: last -n 5
        log_name: system.logins
        description: "Last 5 system logins"
        output_type: log

receivers:
  shell:
    collection_interval: 60s
    commands:
      - name: system_metrics_auto
        command: hyptop -b -n 1 | awk 'BEGIN {printf "%-12s %-10s %-8s %-12s\n","system","cpucount","cpu%","memoryinGB"}$2 ~ /^[0-9]+$/ {printf "%-12s %-10s %-8s %-12s\n",$1,$2,$3,$5}'
        metric_name: system.metrics.shell.hypervisor
        description: "System CPU and Memory metrics"
        output_type: metric

receivers:
  shell:
    collection_interval: 60s
    commands:
      - name: system_metrics_regex
        command: hyptop -b -n 1 | awk 'BEGIN {printf "%-12s %-10s %-8s %-12s\n","system","cpucount","cpu%","memoryinGB"}$2 ~ /^[0-9]+$/ {printf "%-12s %-10s %-8s %-12s\n",$1,$2,$3,$5}'
        metric_name: system.metrics.shell.hypervisor
        description: "System CPU and Memory metrics"
        output_type: metric
        row_regex: '^\s*(\S+)\s+(\d+)\s+([\d.]+)\s+([\d.]+)\s*$'
        metric_names:
          - system
          - cpucount
          - cpu
          - memoryinGB
        descriptions:
          - System Name
          - CPU Count
          - CPU Usage Percentage
          - Memory Usage in GB
        field_types:
          - Attribute  # system is an identifier, not a metric
          - Gauge      # cpucount is a numeric metric
          - Gauge      # cpu is a numeric metric
          - Gauge      # memoryinGB is a numeric metric
        labels:
          source: "hyptop"

      - name: process_stats
        command: ps aux | grep myapp | awk '{print $2, $3, $4}'
        metric_name: process.metrics
        description: "Process CPU and Memory usage"
        output_type: metric
        row_regex: '^\s*(\d+)\s+([\d.]+)\s+([\d.]+)\s*$'
        metric_names:
          - pid
          - cpu_percent
          - mem_percent
        descriptions:
          - Process ID
          - CPU Usage Percentage
          - Memory Usage Percentage
        field_types:
          - Attribute  # PID is an identifier, not a gauge
          - Gauge      # CPU percentage is a metric
          - Gauge      # Memory percentage is a metric
        labels:
          app: "myapp"

Use automatic parsing in the following instances:

• You have simple numeric outputs or standard tabular data.
• You want quick setup without regex configuration.
• All numeric fields should be treated as metrics.

Use regex-based parsing in the following instances:

• You need to distinguish between identifiers (such as, PID or system names) and actual metrics
• You have irregular or variable output formats.
• You want explicit control over field types and names.
• You need custom field descriptions.

For IDOT, you must configure the OTLP exporter to send data to the Instana backend which is a default option.

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 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 that it targets the right endpoint and handles the self-signed certificate correctly.

Alternatively, you can report data through the local Instana agent on the same host. This option requires specific configuration during installation and in the configuration files.

sudo ./instana_otelcol_setup.sh -e 127.0.0.1:4317 -a <INSTANA_KEY> -H http://127.0.0.1:4318 -o <INSTANA_OPAMP_ENDPOINT> -u true

INSTANA_OTEL_ENDPOINT_GRPC=http://127.0.0.1:4317
INSTANA_OTEL_ENDPOINT_HTTP=http://127.0.0.1:4318

INSTANA_OPAMP_ENDPOINT=wss://<opamp-endpoint-url>:443/v1/opamp

exporters:
  otlphttp:
    endpoint: http://127.0.0.1:4318
    tls:
      insecure: true