Internal documentation only
This page has been marked as draft.
How to configure OpenTelemetry plugin with Collection Agent
The OpenTelemetry plugin has been available in Geneos version GA6.0 and above. This article aims to provide an example monitoring a demo application to help users get started.
General Prerequisites Copied
Users should review OpenTelemetry plugin documentation and Geneos Compatibility Matrix.
- Gateway and Netprobe version should be up-to-date
- Gateway Setup Editor schema needs to match Gateway and Netprobe version
- Netprobe is configured with compatible Java version
- License tokens for “opentelemetry-plugin” are available in Licence Daemon
Netprobe and Collection Agent setup Copied
The Geneos OpenTelemetry plugin documentation provides steps to configure the gateway. The configuration is located under the Dynamic Entities folder in Gateway Setup Editor.
We have created a sample gateway setup XML file as an attachment in this article.
- Collectors: When Open-Telemetry plugin is selected from the drop-down box, a YAML template is populated automatically. We are leaving only the top section as a minimal example, and removing the “authentication” and “tls” sections onwards.
- Mapping: We have created example for Collection Agent and OpenTelemetry with mostly default options. The OpenTelemetry mapping is customized to detect label “service.name” as the Managed Entity name, and label “scope.name” as the Dataview name. A few unnecessary labels have been ignored.
- Mapping Types: We have used this to link up the Collectors and Mappings.
- Collection Agent Parameters: We can pass YAML configuration and Java parameters to the Collection Agent.
Case (a) Normal Netprobe (non self-announcing) Copied
In Gateway Setup Editor, user should go to the desired Netprobe and select the Dynamic Entities tab. Choose the Mapping Type and Collection Agent Parameters as needed.
Case (b) Self-Announcing Netprobe Copied
User should include the Dynamic Entities configuration as part of the Netprobe setup file. The XML tags should be placed just before the
<dynamicEntities>
<collectionAgentParameters>My Collection Agent Parameters</collectionAgentParameters>
<mappingType>My OTel Mapping Type</mappingType>
</dynamicEntities>
Verification Copied
Users can check with “netstat” command on the Netprobe server. The Collection Agent should listen to port 4317 if the configuration is successful.
Example OpenTelemetry application Copied
One ITRS staff member has created a simple command line for demo or testing purposes. It tries to connect an OpenTelemetry collector and publishes a single metric. The OTEL_EXPORTER_OTLP_ENDPOINT environment variable points to port 4317 of the Netprobe server.
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
./metrics-linux
The command returns no output if it is successful. Otherwise, it would return an error message.
We have collected the most common errors below.
- Unable to resolve hostname
failed to upload metrics: context deadline exceeded: rpc error: code = Unavailable desc = name resolver error: produced zero addresses
- Connection refused
failed to upload metrics: context deadline exceeded: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:4317: connect: connection refused"
- SSL connection failure
failed to upload metrics: context deadline exceeded: rpc error: code = Unavailable desc = connection error: desc = "transport: authentication handshake failed: EOF"
- Timed out
failed to upload metrics: context deadline exceeded: rpc error: code = DeadlineExceeded desc = received context error while waiting for new LB policy update: context deadline exceeded
Active Console output Copied
The Active Console should display a dataview with a single metric as below.
Further Reading Copied
- ITRS Release Notes and Compatibility Matrix
- Geneos Collection Agent documentation
- OpenTelemetry plugin documentation
- OpenTelemetry plugin demo video Dec 2022 (link to YouTube)