Skip to main content

OpenTelemetry Collector Setup

Pre-requisite​

note

If you can't access @ewam/opentelemetry-plugin then follow the Azure setup tutorial.

Difficulty: Medium

Introduction​

You now have your ewam-opentelemetry-plugin and you would like to setup the collector!
The OpenTelemetry collector main jobs are to:

  • receive telemetry data (here we are only sending traces but it can also do logs and metrics)
  • process them
  • export them to whatever you want
    We will go through how to retrieve the OpenTelemetry collector (otelcol), how to configure it, and how to run it.

Retrieve the OpenTelemetry collector​

Configuration​

The OpenTelemetry Collector follows a configuration file in yaml.
The configuration is detailed on the official documentation: https://opentelemetry.io/docs/collector/configuration/
The content of the core distribution is described in the manifest

tip

You can use environment variable in the yaml file like so: ${env:YOUR_ENV_VAR}.
The syntax for the components is type/NAME, must be unique, the name part is optional.

  1. Create a file collector-config.yaml
  2. Setup the receivers to receive data from the plugin using gRPC
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:WAM_OPENTELEMETRY_COLLECTOR_ENDPOINT}
important

The env var WAM_OPENTELEMETRY_COLLECTOR_ENDPOINT is describe in the @ewam/opentelemetry-plugin readme.
The endpoint MUST match where the plugin is sending the data.
If you don't have access to that env var then write directly the endpoint and ensure it matches the env var at all time.

  1. Setup the processors, handling the received data.
    We are going to configure 3 processors:

    Many more processors are available, refer to https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 4000
    spike_limit_mib: 800
  filter/ottl:
    error_mode: ignore
    traces:
      span:
        - 'instrumentation_scope.name == "RaiseError" and name == "No Error"'  # Drop RaiseError No Error
        # Filter actions
        - 'instrumentation_scope.name == "Action" and (attributes["uiagent.scenario.name"] != "MethodTypeAsPushButton" and attributes["uiagent.scenario.name"] != "WithActionBackGroundBMPPushButton")'
  batch:
    timeout: 30s
    send_batch_size: 200
    send_batch_max_size: 1000
  1. Setup the exporters, sending the traces (after being processed) to whatever you need.
exporters:
  file:
    path: ./traces/traces.wamt
tip

Here we are exporting to a .wamt file, which is a new format available with eWam 8+

tip

This is where you setup your vendor specific exporter.
You might need a contrib, refer to the manifest (link above) as well as your vendor specific documentation.
Although, the exporter otlp (gRPC) and otlphttp are available in the core distrib and everything should be reachable with those.

Vendor documentation examples:

  1. Setup the service, to enable your components. Nothing is enabled if you don't specify it inside the service
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, filter/ottl, batch]
      exporters: [file]

The full file including an example with DataDog looks like that:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: ${env:WAM_OPENTELEMETRY_COLLECTOR_ENDPOINT}

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 4000
    spike_limit_mib: 800
  filter/ottl:
    error_mode: ignore
    traces:
      span:
        - 'instrumentation_scope.name == "RaiseError" and name == "No Error"'  # Drop RaiseError No Error
        # Filter actions
        - 'instrumentation_scope.name == "Action" and (attributes["uiagent.scenario.name"] != "MethodTypeAsPushButton" and attributes["uiagent.scenario.name"] != "WithActionBackGroundBMPPushButton")'
  batch:
    timeout: 30s
    send_batch_size: 200
    send_batch_max_size: 1000

exporters:
  file:
    path: ./traces/traces.wamt

  datadog/Wyde:
    api:
      site: us5.datadoghq.com
      key: ${env:DATADOG_WYDE_API_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, filter/ottl, batch]
      exporters: [file, datadog/Wyde]

Run​

You have to run your binary otelcol.exe or otelcol-contrib.exe with the option --config "PATH_TO_collector-config.yaml".

  1. Add the required environment variables in Windows
  2. Create a service for the collector
    Run in cmd (adjust the command accordingly):

    sc create otelcol:4317 binPath="\"C:\PATH\otelcol-contrib.exe\" --config \"C:\PATH\collector-config.yaml\" start=auto"

If you don't have the rights then you can make a script to run the .exe, using for example Node.js. The collector is a server.

Conclusion​

You now have an OpenTelemetry Collector ready to handle traces sent by the plugin @ewam/opentelemetry-plugin.