Open Telemetry Mappings Troubleshooting

Overview

The SUSE Observability CLI can be used to troubleshoot an Open Telemetry topology synchronization and fix issues that might prevent topology data from being correctly ingested and displayed in SUSE® Observability. This page describes the general troubleshooting steps to take when debugging such an issue.

General troubleshooting steps

Verify that the Open Telemetry mapping exists.
- If no mappings are present, then verify the installation of the Open Telemetry stackpack.
When missing components or relations of a certain type, get the status of the mapping.
- Check the latency metrics to determine if data is flowing or if there is a miscommunication between the Open Telemetry collector and the platform.
- Fix the mapping errors reported as those are preventing some topology elements to be synced.
- A potential source of mappings "silently" not being processed as expected could be the conditions/filtering applied in the input field. For example, if a condition is false, there’s no error - but the mapping is "skipped".

Useful CLI commands

List Open Telemetry component mappings

Returns a list of all current Open Telemetry mappings.

$ sts otel-component-mapping list
NAME                   | IDENTIFIER
Database               | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:database
Function Component     | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:function
Host Component         | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:host
Kubernetes Namespace   | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:namespace
Kubernetes Pod         | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:pod
OTel Service Component | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service-instance
OTel Service Instance  | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service
Task Component         | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:task

List Open Telemetry relation mappings

Returns a list of all current Open Telemetry mappings.

$ sts otel-relation-mapping list
NAME                                               | IDENTIFIER
Database Relation                                  | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database
Executes Relation (Function)                       | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:executes-function
Executes Relation (Host)                           | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:executes-host
Executes Relation (Task)                           | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:executes-task
Kubernetes to OTEL Relation                        | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:kubernetes-to-otel
OTel Async Relation (Consumer -> Peer)             | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:asynchronous-consumer-peer
OTel Async Relation (Producer -> Consumer)         | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:asynchronous-producer-consumer
OTel Async Relation (Producer -> Peer)             | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:asynchronous-producer-peer
OTel Synchronous Relation                          | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:synchronous
OTel service instance provided-by service relation | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:provided-by

Show an Open Telemetry component or relation mappings status

The Open Telemetry component mapping status command returns the aggregated latency, throughput metrics and number of topology elements created. This is helpful when debugging why a particular part of the topology takes a long time to be synchronised. The output includes a section Mapping errors that will signal any issues occurring when applying the mapping rules to the Open Telemetry data.

$ sts otel-component-mapping status --identifier urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service


Otel Component Mapping:
NAME                  | IDENTIFIER                                                           | COMPONENTS | RELATIONS
OTel Service Instance | urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service | 9          | 0


Otel Component Mapping Metrics:
METRIC          | 500S AGO | 500-1000S AGO | 1000-1500S AGO
latency seconds | 44.45    | 44.45         | 41.19

Analogous there is an Open Telemetry relation mapping status

$ sts otel-relation-mapping status --identifier urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database


Otel Relation Mapping:
NAME              | IDENTIFIER                                                           | COMPONENTS | RELATIONS
Database Relation | urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database | 0          | 2


Otel Relation Mapping Metrics:
METRIC          | 500S AGO | 500-1000S AGO | 1000-1500S AGO
latency seconds | 43.404   | 43.404        | 39.978


Otel Relation Mapping Errors:
No otel relation mapping errors found.

Get the full Open Telemetry component or mapping

To quickly view the full mapping definition for a component or relation mapping use the get command:

$ sts otel-component-mapping get --identifier urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service
# Output omitted for brevity

Or for relation mappings:

$ sts otel-relation-mapping get --identifier urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database
# Output omitted for brevity

Edit an Open Telemetry component or relation mapping

If you notice issues in the mapping definition, edit it directly using the edit command. This will open the mapping in your default text editor.

$ sts otel-component-mapping edit --identifier urn:stackpack:open-telemetry-2:shared:otel-component-mapping:service
# Opens the mapping in your default text editor

Or for relation mappings:

$ sts otel-relation-mapping edit --identifier urn:stackpack:open-telemetry-2:shared:otel-relation-mapping:database
# Opens the mapping in your default text editor

If the mapping was modified, the changes will be applied when you save and exit the editor.

Remember to update the mapping definitions in your StackPack source files to keep them in sync with any changes made via the CLI.