Solução de Problemas de Mapeamentos do OpenTelemetry

Visão Geral

O SUSE Observability CLI pode ser usado para solucionar problemas de sincronização de topologia do OpenTelemetry e corrigir questões que podem impedir que os dados da topologia sejam corretamente ingeridos e exibidos em SUSE® Observability. Esta página descreve as etapas gerais de solução de problemas a serem seguidas ao depurar esse problema.

Etapas gerais de solução de problemas

  1. Verifique se o mapeamento do OpenTelemetry existe.

    • Se não houver mapeamentos presentes, verifique a instalação do stackpack do OpenTelemetry.

  2. Quando componentes ou relações de um certo tipo estiverem ausentes, obtenha o status do mapeamento.

    • Verifique as métricas de latência para determinar se os dados estão fluindo ou se há uma falha de comunicação entre o coletor do OpenTelemetry e a plataforma.

    • Corrija os erros de mapeamento relatados, pois estes estão impedindo que alguns elementos da topologia sejam sincronizados.

    • Uma possível fonte de mapeamentos que não estão sendo processados "silenciosamente" como esperado pode ser as condições/filtros aplicados no campo de entrada. Por exemplo, se uma condição for falsa, não há erro – mas o mapeamento é "ignorado".

Comandos úteis da CLI

Listar mapeamentos de componentes do OpenTelemetry

Retorna uma lista de todos os mapeamentos atuais do OpenTelemetry.

$ 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

Listar mapeamentos de relações do OpenTelemetry

Retorna uma lista de todos os mapeamentos atuais do OpenTelemetry.

$ 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

Mostrar o status de mapeamentos de componentes ou relações do OpenTelemetry

O comando de status do mapeamento de componentes do OpenTelemetry retorna a latência agregada, métricas de throughput e o número de elementos de topologia criados. Isso é útil ao depurar por que uma parte específica da topologia leva muito tempo para ser sincronizada. A saída inclui uma seção Mapping errors que sinalizará quaisquer problemas ocorrendo ao aplicar as regras de mapeamento aos dados do OpenTelemetry.

$ 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

De forma análoga, há um status de mapeamento de relação do OpenTelemetry.

$ 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.

Obtenha o componente completo do OpenTelemetry ou o mapeamento.

Para visualizar rapidamente a definição completa do mapeamento de um componente ou mapeamento de relação, use o comando get:

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

Ou para mapeamentos de relação:

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

Edite um componente do OpenTelemetry ou um mapeamento de relação.

Se você notar problemas na definição do mapeamento, edite-a diretamente usando o comando edit. Isso abrirá o mapeamento no seu editor de texto padrão.

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

Ou para mapeamentos de relação:

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

Se o mapeamento foi modificado, as alterações serão aplicadas quando você salvar e fechar o editor.

Lembre-se de atualizar as definições de mapeamento em seus arquivos de origem do StackPack para mantê-las em sincronia com quaisquer alterações feitas via CLI.