Sending OpenTelemetry data to the Instana backend

Telemetry data can be sent in OTLP format directly from applications or systems to the Instana backend. Complete the following configurations:

Prerequisites

  • The special endpoints of the backend otlp-acceptor component are used when OpenTelemetry data is sent.

    In the following configuration example, the OpenTelemetry collector is used to connect to the Instana backend otlp-acceptor component:

    exporters:
  otlp:
    endpoint: INSTANA_OTLP_GRPC_BACKEND:4317
    headers:
      x-instana-key: xxxxxxx

  • You must set the required Instana agent key for validation. Set the x-instana-key field with the agent key of the Instana for targeting the Instana backend.

Creating the required resource attribute or environment variable

The Instana backend requires the host.id, faas.id, or device.id resource attribute, or you can also set x-instana-host as an environment variable.

If the OpenTelemetry Collector is deployed in a Daemonset mode, the OpenTelemetry Collector is located in the same host of the applications that send out OpenTelemetry data. You can also set the x-instana-host header by using the OTLP exporter.

exporters:
  otlp:
    endpoint: INSTANA_OTLP_GRPC_BACKEND:4317
    headers:
      x-instana-key: xxxxxxx
      x-instana-host: xxxx

Notes:

  • Set the x-instana-key field with the agent key of the Instana agent for targeting the Instana backend.
  • Set the x-instana-host field with the host ID if no host.id, faas.id, or device.id resource attribute is defined in your application or system.
  • Set the endpoint field with the correct domain name of the otlp-acceptor component of the Instana backend.
  • Instana uses OTLP standard port numbers, such as 4317 for OTLP/gRPC and 4318 for OTLP/HTTP. Port 443 is also supported for OTLP/HTTP.

Configuring Self-Hosted Instana

On Instana self-hosted, port 443 is used for OTLP/gRPC and OTLP/HTTP protocols. The following domain names are used for the protocols:

otlp-grpc.<base_domain> for OTLP/gRPC otlp-http.<base_domain> for OTLP/HTTP

To send the OpenTelemetry data to the Instana backend, complete the following steps:

  1. Make sure the two DNS entries otlp-http.<base_domain> and otlp-grpc.<basedomain> are created for the otlp-acceptor component in your Instana backend.

  2. Configure the OTLP exporter to use with OpenTelemetry collector and complete one of the following steps:

    • OTLP exporter with certification verification:

      1. Get CA file from self-hosted instana

        • For self-hosted standard edition:
          kubectl get secret instana-tls -n instana-core -o jsonpath='{.data.ca\.crt}'|base64 -d > ca.crt
        • For self-hosted custom edition which certificate is generated by openssl command:
          kubectl get secret instana-tls -n instana-core -o jsonpath='{.data.tls\.crt}'|base64 -d > tls.crt

      2. Copy ca.crt to the location of the OpenTelemetry collector environment:

        exporters:
  otlp:
    endpoint: otlp-grpc.<base_domain>:443
    tls:
      insecure: false
      ca_file: <path_to_cert_file>/<cert_file_name>
    headers:
      x-instana-key: xxxxxx
      x-instana-host: xxxxxx

    • OTLP exporter without certification verification:

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

Forwarding Telemetry data to the Instana backend with the OpenTelemetry Collector

To forward OpenTelemetry data to the Instana backend, complete the following steps:

  1. Identify your Instana deployment region. The endpoint for the Instana backend varies based on the deployment region. To find the Instana region that is dedicated to your environment, on the Instana UI, go to the navigation menu, and then click More > About Instana. The Instana dialog is displayed. You can see the Instana deployment region in the dialog.

    Each Instana SaaS environment is associated with a specific region name, such as blue, red, green, orange, or coral. For detailed information about the endpoint of the Instana backend otlp-acceptor, see Endpoints of Instana backend otlp-acceptor.

  2. Configure an OTLP/gRPC or OTLP/HTTP connection to the Instana backend. For example, if you are using the Instana blue environment, you can configure an OTLP/gRPC or OTLP/HTTP connection to the Instana backend by using the following configuration:

    • OTLP/gRPC

      exporters:
  otlp:
    endpoint: otlp-blue-saas.instana.io:4317
    headers:
      x-instana-key: xxxx
...
service:
  pipelines:
    traces:
      receivers: [...]
      processors: [...]
      exporters: [..., otlp]
    metrics:
      receivers: [...]
      processors: [...]
      exporters: [..., otlp]
    logs:
      receivers: [...]
      processors: [...]
      exporters: [..., otlp]

      Set the x-instana-key field with the agent key of the Instana agent for targeting the Instana backend.

    • OTLP/HTTP

      exporters:
  otlphttp:
    endpoint: "otlp-blue-saas.instana.io:4318"
    headers:
      x-instana-key: xxxx
...
service:
  pipelines:
    traces:
      receivers: [...]
      processors: [...]
      exporters: [..., otlphttp]
    metrics:
      receivers: [...]
      processors: [...]
      exporters: [..., otlphttp]
    logs:
      receivers: [...]
      processors: [...]
      exporters: [..., otlphttp]

Configuring the resource attributes

The Instana backend requires a host.id, faas.id, or device.id resource attribute. Alternatively, you can set x-instana-host as an environment variable.

If the OpenTelemetry Collector is deployed in the DaemonSet mode, that is, the OpenTelemetry Collector is located in the same host of the applications that send the OpenTelemetry data, you can set the x-instana-host header by using the OTLP exporter. See the following example:

exporters:
  otlp:
    endpoint: otlp-blue-saas.instana.io:4317
    headers:
      x-instana-key: xxxxxxx
      x-instana-host: xxxx

You must specify the host ID in the x-instana-host field if no host.id, faas.id, or device.id resource attribute is defined in your application or system.

Alternatively, you can add the host.id resource attribute is to use the resource processor:

processors:
  resource:
    attributes:
    - key: host.id
      action: upsert
      value: "myhost1.ibm.com"

After you complete all configuration changes in the agent configuration.yaml file, run the following command to use the OpenTelemetry Collector:

otel-contrib --config configuration.yaml

Endpoints of the Instana backend otlp-acceptor

In the following table, you can see the domain names of the Instana backend otlp-acceptor for different Instana SaaS environments. For more information about the Instana SaaS environment, see Integrating with OpenTelemetry by using the OpenTelemetry Collector.

Instana SaaS environment Domain name of otlp-accepter
blue otlp-blue-saas.instana.io
red otlp-red-saas.instana.io
green otlp-green-saas.instana.io
orange otlp-orange-saas.instana.io
coral otlp-coral-saas.instana.io
teal HTTP: otlp-http-teal-saas.instana.io
GRPC: otlp-grpc-teal-saas.instana.io
mizu HTTP: otlp-http-mizu-saas.instana.io
GRPC: otlp-grpc-mizu-saas.instana.io

All endpoints of the Instana backend otlp-acceptor in SaaS environments are TLS-enabled.