From 1d60d428bc0bf8821ce2f540290b60f0a98b0519 Mon Sep 17 00:00:00 2001 From: Alejandro Acevedo Date: Thu, 27 Nov 2025 10:52:37 +0100 Subject: [PATCH 1/2] STAC-23693: otel mappings troubleshooting guide --- docs/latest/antora.yml | 3 + docs/latest/modules/en/nav.adoc | 5 + .../pages/setup/otel/otelmappings/README.adoc | 4 + .../setup/otel/otelmappings/concepts.adoc | 4 + .../otel/otelmappings/troubleshooting.adoc | 96 +++++++++++++++++++ 5 files changed, 112 insertions(+) create mode 100644 docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc create mode 100644 docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc create mode 100644 docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc diff --git a/docs/latest/antora.yml b/docs/latest/antora.yml index 8f2b5924..62fabca2 100644 --- a/docs/latest/antora.yml +++ b/docs/latest/antora.yml @@ -3,5 +3,8 @@ title: SUSE Observability version: latest display_version: Latest start_page: en:classic.adoc +asciidoc: + attributes: + stackpacks2_enabled: false nav: - modules/en/nav.adoc \ No newline at end of file diff --git a/docs/latest/modules/en/nav.adoc b/docs/latest/modules/en/nav.adoc index c31732e1..ccc97180 100644 --- a/docs/latest/modules/en/nav.adoc +++ b/docs/latest/modules/en/nav.adoc @@ -93,6 +93,11 @@ **** xref:setup/otel/instrumentation/node.js/auto-instrumentation-of-lambdas.adoc[Auto-instrumentation of Lambdas.js] *** xref:setup/otel/instrumentation/dot-net.adoc[.NET] *** xref:setup/otel/instrumentation/sdk-exporter-config.adoc[SDK Exporter configuration] +ifdef::stackpacks2_enabled[] +** xref:setup/otel/otelmappings/README.adoc[Open Telemetry Mappings] +*** xref:setup/otel/otelmappings/concepts.adoc[Concepts] +*** xref:setup/otel/otelmappings/troubleshooting.adoc[Troubleshooting] +endif::stackpacks2_enabled[] ** xref:setup/otel/troubleshooting.adoc[Troubleshooting] * CLI ** xref:setup/cli/cli-sts.adoc[SUSE Observability CLI] diff --git a/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc b/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc new file mode 100644 index 00000000..b0a71bbd --- /dev/null +++ b/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc @@ -0,0 +1,4 @@ += Getting Started with Open Telemetry Mappings +:revdate: 2025-11-26 +:page-revdate: {revdate} +:description: Overview of Open Telemetry Mappings \ No newline at end of file diff --git a/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc b/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc new file mode 100644 index 00000000..6d515cb0 --- /dev/null +++ b/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc @@ -0,0 +1,4 @@ += Open Telemetry Mappings Concepts +:revdate: 2025-11-26 +:page-revdate: {revdate} +:description: Open Telemetry Mappings Concepts \ No newline at end of file diff --git a/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc b/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc new file mode 100644 index 00000000..1240d583 --- /dev/null +++ b/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc @@ -0,0 +1,96 @@ += Open Telemetry Mappings Troubleshooting +:revdate: 2025-11-26 +:page-revdate: {revdate} +:description: Troubleshooting Open Telemetry Mappings + +== Overview + +The xref:/setup/cli/cli-sts.adoc[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 + +. xref:/setup/otel/otelmappings/troubleshooting.adoc#_list_open_telemetry_component_mappings[Verify that the open telemetry mapping exists]. +** If no mappings are present verify that the open telemetry stackpack is installed +. When missing components or relations of a certain type, xref:/setup/otel/otelmappings/troubleshooting.adoc#_show_an_open_telemetry_component_or_relation_mappings_status[get the status of the mapping]. +** Check the latency metrics to determine if data is flowing or if the issue could be a communication issue between the open telemetry collector and the platform. +** Fix the mapping errors reported as those are preventing some topology elements to be synced. + +== Useful CLI commands + +=== List open telemetry component mappings + +Returns a list of all current open telemetry mappings. + +[,sh] +---- +$ 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. + +[,sh] +---- +$ 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 ana amount 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. + +[,sh] +---- +$ 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 +[,sh] +---- +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. +---- \ No newline at end of file From 725b5296937e2074bad2e3ea5185d26a3d1e4e07 Mon Sep 17 00:00:00 2001 From: Alejandro Acevedo Date: Thu, 27 Nov 2025 15:52:16 +0100 Subject: [PATCH 2/2] STAC-23693: Address review comments --- .../modules/en/pages/setup/otel/otelmappings/README.adoc | 4 +++- .../modules/en/pages/setup/otel/otelmappings/concepts.adoc | 4 +++- .../en/pages/setup/otel/otelmappings/troubleshooting.adoc | 5 ++++- 3 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc b/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc index b0a71bbd..65571ae2 100644 --- a/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc +++ b/docs/latest/modules/en/pages/setup/otel/otelmappings/README.adoc @@ -1,4 +1,6 @@ +ifdef::stackpacks2_enabled[] = Getting Started with Open Telemetry Mappings :revdate: 2025-11-26 :page-revdate: {revdate} -:description: Overview of Open Telemetry Mappings \ No newline at end of file +:description: Overview of Open Telemetry Mappings +endif::stackpacks2_enabled[] \ No newline at end of file diff --git a/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc b/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc index 6d515cb0..26d57a39 100644 --- a/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc +++ b/docs/latest/modules/en/pages/setup/otel/otelmappings/concepts.adoc @@ -1,4 +1,6 @@ +ifdef::stackpacks2_enabled[] = Open Telemetry Mappings Concepts :revdate: 2025-11-26 :page-revdate: {revdate} -:description: Open Telemetry Mappings Concepts \ No newline at end of file +:description: Open Telemetry Mappings Concepts +endif::stackpacks2_enabled[] \ No newline at end of file diff --git a/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc b/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc index 1240d583..0c3787f4 100644 --- a/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc +++ b/docs/latest/modules/en/pages/setup/otel/otelmappings/troubleshooting.adoc @@ -1,3 +1,4 @@ +ifdef::stackpacks2_enabled[] = Open Telemetry Mappings Troubleshooting :revdate: 2025-11-26 :page-revdate: {revdate} @@ -14,6 +15,7 @@ The xref:/setup/cli/cli-sts.adoc[SUSE Observability CLI] can be used to troubles . When missing components or relations of a certain type, xref:/setup/otel/otelmappings/troubleshooting.adoc#_show_an_open_telemetry_component_or_relation_mappings_status[get the status of the mapping]. ** Check the latency metrics to determine if data is flowing or if the issue could be a communication issue 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 @@ -93,4 +95,5 @@ latency seconds | 43.404 | 43.404 | 39.978 Otel Relation Mapping Errors: No otel relation mapping errors found. ----- \ No newline at end of file +---- +endif::stackpacks2_enabled[] \ No newline at end of file