As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Observabilidade no Amazon Service OpenSearch
<a name="observability"></a>

Observabilidade é a prática de compreender o estado interno e o desempenho de sistemas complexos examinando suas saídas. O monitoramento tradicional indica que o sistema está inativo; a observabilidade ajuda você a entender o motivo, permitindo que você faça novas perguntas sobre seus dados de telemetria.

## O que o Amazon OpenSearch Service oferece
<a name="observability-what"></a>

O Amazon OpenSearch Service fornece uma solução unificada de observabilidade coletando, correlacionando e visualizando três tipos de dados de telemetria:
+ **Registros — registros** de eventos com carimbo de data e hora.
+ **Traços** — End-to-end jornada de solicitações por meio de serviços distribuídos.
+ **Métricas** — dados de séries temporais que representam a integridade do sistema, por meio da integração de consulta direta do Amazon Managed Service for Prometheus.

Ao reuni-los em uma única interface, o Amazon OpenSearch Service ajuda as equipes operacionais e os desenvolvedores a detectar, diagnosticar e resolver problemas com mais rapidez. SREs

## A abordagem da Amazon OpenSearch Service para observabilidade
<a name="observability-approach"></a>

O Amazon OpenSearch Service se diferencia de três maneiras principais:
+ **OpenTelemetry-nativo com OpenSearch ingestão como última milha** — Padronize OTel para instrumentação e coleta. O Amazon OpenSearch Ingestion serve como um pipeline totalmente gerenciado que filtra, enriquece, transforma e roteia seus dados de telemetria antes da indexação.
+ **Registros, rastreamentos e métricas unificados na OpenSearch interface do usuário** — analise todos os três tipos de sinais em um único espaço de trabalho de observabilidade. Correlacione um rastreamento lento aos registros do aplicativo ou sobreponha as métricas do Prometheus em seus painéis de serviço.
+ **Linguagens de consulta orientadas por propósitos** — use a [Piped Processing Language (PPL)](https://observability.opensearch.org/docs/ppl/) para registros e rastreamentos e o ProMQL para métricas. Cada idioma é otimizado para seu tipo de sinal, oferecendo consultas expressivas sem concessões.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/otel-sdk-service.png)


**nota**  
Os recursos de observabilidade descritos nesta seção estão disponíveis somente na OpenSearch interface do usuário. Eles não estão disponíveis nos OpenSearch painéis. Para novas cargas de trabalho de observabilidade, recomendamos configurar um [Usando a OpenSearch interface do usuário no Amazon OpenSearch Service](application.md) com um espaço de trabalho de observabilidade.

# Conceitos básicos
<a name="observability-get-started"></a>

Coloque sua pilha de observabilidade em funcionamento AWS e comece a enviar dados de telemetria em minutos.

## Início rápido
<a name="observability-get-started-quick"></a>

A maneira mais rápida de implantar uma pilha end-to-end de observabilidade AWS é o instalador da CLI. Ele cria os recursos a seguir:
+ Um domínio do Amazon OpenSearch Service
+ Um Amazon Managed Service para o espaço de trabalho Prometheus
+ Um pipeline de OpenSearch ingestão da Amazon
+ Um aplicativo de OpenSearch interface de usuário com um espaço de trabalho de observabilidade

Opcionalmente, o instalador executa uma instância do EC2 com o OpenTelemetry Demo para amostra de telemetria.

Execute o comando a seguir para iniciar a instalação:

```
bash -c "$(curl -fsSL https://raw.githubusercontent.com/opensearch-project/observability-stack/main/install.sh)" -- --deployment-target=aws
```

A instalação leva aproximadamente 15 minutos.

## Implantação do CDK
<a name="observability-get-started-cdk"></a>

Para infrastructure-as-code, use o AWS CDK. A implantação do CDK cria duas pilhas:


| Stack | O que ele cria | Tempo de implantação | 
| --- | --- | --- | 
| ObsInfra | OpenSearch domínio, espaço de trabalho do Amazon Managed Service para Prometheus, fonte de dados de consulta direta, função do pipeline IAM | \$117 minutos | 
| ObservabilityStack | Mapeamento detalhado de controle de acesso, pipeline de OpenSearch ingestão, aplicativo de OpenSearch interface do usuário, inicialização do painel, carga de trabalho de demonstração (opcional) | \$16 minutos | 

Execute os seguintes comandos para implantar:

```
cd aws/cdk
npm install
cdk deploy --all
```

Para obter mais informações, consulte o [README de implantação do CDK](https://github.com/opensearch-project/observability-stack/tree/main/aws/cdk) em. GitHub

## Envio de telemetria
<a name="observability-get-started-send"></a>

Ambos os métodos de implantação criam um endpoint OpenSearch de ingestão que aceita dados OTLP. Configure seu OTel Collector para exportar usando a autenticação SigV4:

```
extensions:
  sigv4auth:
    region: us-west-2
    service: osis

exporters:
  otlphttp/logs:
    logs_endpoint: ${OSIS_ENDPOINT}/v1/logs
    auth: { authenticator: sigv4auth }
    compression: none
  otlphttp/traces:
    traces_endpoint: ${OSIS_ENDPOINT}/v1/traces
    auth: { authenticator: sigv4auth }
    compression: none
  otlphttp/metrics:
    metrics_endpoint: ${OSIS_ENDPOINT}/v1/metrics
    auth: { authenticator: sigv4auth }
    compression: none
```

**nota**  
O principal do IAM está enviando dados, necessidades `osis:Ingest` e `aps:RemoteWrite` permissões no ARN do pipeline.

## Saiba mais
<a name="observability-get-started-learn-more"></a>

Use os seguintes recursos para saber mais sobre o envio de dados de telemetria:
+ [OpenTelemetry guias de instrumentação (por idioma)](https://observability.opensearch.org/docs/send-data/applications/)
+ [Monitoramento de infraestrutura (Docker AWS, Kubernetes, Prometheus)](https://observability.opensearch.org/docs/send-data/infrastructure/)
+ [OTel Configuração do coletor](https://observability.opensearch.org/docs/send-data/opentelemetry/collector/)
+ [Pipeline de dados e processamento em lotes](https://observability.opensearch.org/docs/send-data/data-pipeline/)
+ [Visão geral da OpenSearch ingestão da Amazon](ingestion.md) neste guia

# Ingestão de telemetria de aplicativos
<a name="observability-ingestion"></a>

Para usar os recursos de observabilidade no Amazon OpenSearch Service, você precisa ingerir rastreamentos, registros e métricas do aplicativo. Esta página aborda a configuração dos pipelines de OpenTelemetry coleta e OpenSearch ingestão para processar e rotear dados de telemetria para o Amazon Managed Service for OpenSearch Prometheus.

## Configurando o coletor OpenTelemetry
<a name="observability-ingestion-otel"></a>

O coletor OpenTelemetry (OTel) é o ponto de entrada para toda a telemetria de aplicativos. Ele recebe dados por meio do OTLP e encaminha rastreamentos e registros para o OpenSearch Ingestion enquanto envia métricas para o Prometheus.

Você pode configurar o OTel Collector usando uma das seguintes abordagens:

O OTel Collector exporta rastreamentos e registros para um endpoint de OpenSearch ingestão usando a autenticação SigV4 e métricas para o Amazon Managed Service for Prometheus usando o exportador de gravação remota Prometheus. OpenSearch A ingestão lida com processamento, enriquecimento e roteamento para. OpenSearch

### OTel Configuração do coletor com ingestão OpenSearch
<a name="observability-ingestion-otel-osis"></a>

O exemplo de configuração a seguir usa a autenticação SigV4 para exportar rastreamentos e registros para um endpoint de OpenSearch ingestão e métricas para o Prometheus:

```
extensions:
  sigv4auth:
    region: us-west-2
    service: osis

exporters:
  otlphttp/osis-traces:
    traces_endpoint: ${OSIS_ENDPOINT}/v1/traces
    auth: { authenticator: sigv4auth }
    compression: none
  otlphttp/osis-logs:
    logs_endpoint: ${OSIS_ENDPOINT}/v1/logs
    auth: { authenticator: sigv4auth }
    compression: none
  # Amazon Managed Service for Prometheus via Prometheus Remote Write with SigV4 auth
  prometheusremotewrite/amp:
    endpoint: "https://aps-workspaces.region.amazonaws.com/workspaces/workspace-id/api/v1/remote_write"
    auth:
      authenticator: sigv4auth

service:
  extensions: [sigv4auth]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/osis-traces]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/osis-logs]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheusremotewrite/amp]
```

**nota**  
O principal do IAM está enviando dados, necessidades `osis:Ingest` e `aps:RemoteWrite` permissões no ARN do pipeline.

## Configurando pipelines de OpenSearch ingestão
<a name="observability-ingestion-pipelines"></a>

OpenSearch A ingestão (ou preparador de dados autogerenciado) recebe telemetria do OTel Collector e a processa para monitoramento de desempenho de aplicativos (APM).

### Arquitetura de pipeline
<a name="observability-ingestion-pipeline-arch"></a>

O pipeline processa dados de telemetria nos seguintes estágios:

1. O pipeline de entrada recebe toda a telemetria e encaminha os registros e rastreamentos para subpipelines separados.

1. O pipeline de registros grava dados de registro OpenSearch usando o tipo de `log-analytics-plain` índice.

1. O pipeline de rastreamento distribui extensões para o pipeline de armazenamento bruto e o pipeline do mapa de serviços.

1. O pipeline de rastreamento bruto processa extensões com o `otel_traces` processador e as armazena no tipo de `trace-analytics-plain-raw` índice.

1. O pipeline do mapa de serviços usa o `otel_apm_service_map` processador para gerar topologia e métricas RED (Taxa, Erros, Duração). Ele grava para OpenSearch e para Prometheus por meio de gravação remota.

### Configuração do pipeline
<a name="observability-ingestion-pipeline-config"></a>

O exemplo a seguir mostra uma configuração completa do pipeline para OpenSearch ingestão que abrange todos os tipos de sinais de observabilidade — registros, rastreamentos e métricas. Você pode incluir todos os pipelines ou somente os relevantes ao seu caso de uso. Substitua *placeholder* os valores por suas próprias informações.

```
version: '2'

# Main OTLP pipeline - receives all telemetry and routes by signal type
otlp-pipeline:
  source:
    otlp:
      logs_path: '/pipeline-name/v1/logs'
      traces_path: '/pipeline-name/v1/traces'
      metrics_path: '/pipeline-name/v1/metrics'
  route:
    - logs: 'getEventType() == "LOG"'
    - traces: 'getEventType() == "TRACE"'
    - metrics: 'getEventType() == "METRIC"'
  processor: []
  sink:
    - pipeline:
        name: otel-logs-pipeline
        routes:
          - logs
    - pipeline:
        name: otel-traces-pipeline
        routes:
          - traces
    - pipeline:
        name: otel-metrics-pipeline
        routes:
          - metrics

# Log processing pipeline
otel-logs-pipeline:
  source:
    pipeline:
      name: otlp-pipeline
  processor:
    - copy_values:
        entries:
          - from_key: "time"
            to_key: "@timestamp"
  sink:
    - opensearch:
        hosts:
          - 'https://opensearch-endpoint'
        index_type: log-analytics-plain
        aws:
          serverless: false
          region: 'region'
          sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"

# Trace fan-out pipeline
otel-traces-pipeline:
  source:
    pipeline:
      name: otlp-pipeline
  processor: []
  sink:
    - pipeline:
        name: traces-raw-pipeline
        routes: []
    - pipeline:
        name: service-map-pipeline
        routes: []

# Raw trace storage pipeline
traces-raw-pipeline:
  source:
    pipeline:
      name: otel-traces-pipeline
  processor:
    - otel_traces:
  sink:
    - opensearch:
        hosts:
          - 'https://opensearch-endpoint'
        index_type: trace-analytics-plain-raw
        aws:
          serverless: false
          region: 'region'
          sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"

# Service map generation pipeline (APM)
service-map-pipeline:
  source:
    pipeline:
      name: otel-traces-pipeline
  processor:
    - otel_apm_service_map:
        group_by_attributes:
          - telemetry.sdk.language # Add any resource attribute to group by
        window_duration: 30s
  route:
    - otel_apm_service_map_route: 'getEventType() == "SERVICE_MAP"'
    - service_processed_metrics: 'getEventType() == "METRIC"'
  sink:
    - opensearch:
        hosts:
          - 'https://opensearch-endpoint'
        aws:
          serverless: false
          region: 'region'
          sts_role_arn: "arn:aws:iam::account-id:role/pipeline-role"
        routes:
          - otel_apm_service_map_route
        index_type: otel-v2-apm-service-map
    - prometheus:
        url: 'https://aps-workspaces.region.amazonaws.com/workspaces/workspace-id/api/v1/remote_write'
        aws:
          region: 'region'
        routes:
          - service_processed_metrics

# Metrics processing pipeline
otel-metrics-pipeline:
  source:
    pipeline:
      name: otlp-pipeline
  processor:
    - otel_metrics:
  sink:
    - prometheus:
        url: 'https://aps-workspaces.region.amazonaws.com/workspaces/workspace-id/api/v1/remote_write'
        aws:
          region: 'region'
```

## Verificando a ingestão
<a name="observability-ingestion-verify"></a>

Depois de configurar o OTel coletor e os pipelines, verifique se os dados de telemetria estão fluindo corretamente.
+ **Verificar OpenSearch índices** — Confirme se os seguintes índices existem em seu domínio: `otel-v1-apm-span-*``otel-v2-apm-service-map`, e. `logs-otel-v1-*`
+ **Verifique as metas do Prometheus** — Confirme se o destino de gravação remota do Prometheus está recebendo métricas do pipeline do mapa de serviços.
+ **Verifique na OpenSearch interface do usuário** — navegue até **Observabilidade** e, em seguida, **Monitoramento de aplicativos** para confirmar se seus serviços aparecem.

## Próximas etapas
<a name="observability-ingestion-next"></a>

Depois de verificar se os dados de telemetria foram ingeridos, explore os seguintes tópicos:
+ [Monitoramento de aplicações](observability-app-monitoring.md)— monitore a integridade do aplicativo com mapas de serviços e métricas RED.
+ [Descubra rastros](observability-analyze-traces.md) — Descubra e analise rastreamentos distribuídos.
+ [Descubra registros](observability-analyze-logs.md) — Descubra e consulte registros de aplicativos.
+ [Descubra métricas](observability-metrics.md) — Descubra e consulte as métricas do Prometheus usando o PromQL.

# Conjuntos de dados
<a name="observability-datasets"></a>

Os conjuntos de dados são coleções de índices que representam um agrupamento lógico dos seus dados de observabilidade. Você usa conjuntos de dados para organizar registros e dados de rastreamento para poder consultar e analisar índices relacionados juntos na experiência Discover. Cada conjunto de dados mapeia para um ou mais índices em seu domínio de OpenSearch serviço e define o tipo de dados, o campo de horário e a linguagem de consulta para a página Discover.

## Tipos de conjuntos de dados
<a name="observability-datasets-types"></a>

A tabela a seguir descreve os tipos de conjunto de dados que você pode criar.


| Tipo | Description | Linguagem de consulta | 
| --- | --- | --- | 
| Logs | Agrupa um ou mais índices de registro para consulta e visualização na página Descobrir registros. | PPL | 
| Rastreamentos | Grupos rastreiam índices de abrangência para consulta e visualização na página Discover Traces. | PPL | 

**nota**  
As métricas não exigem um conjunto de dados porque os dados métricos não são armazenados em OpenSearch. As métricas são consultadas diretamente do Amazon Managed Service for Prometheus usando o PromQL.

## Para criar um conjunto de dados de registros
<a name="observability-datasets-create-logs"></a>

Conclua as etapas a seguir para criar um conjunto de dados de registros na OpenSearch interface do usuário.

1. **Em seu espaço de trabalho de observabilidade, expanda **Discover** no painel de navegação à esquerda e escolha Registros.**

1. Escolha **Criar conjunto de dados**.

1. Selecione uma fonte de dados na lista de conexões de OpenSearch serviço disponíveis.  
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/datasets-select-data-source.png)

1. Configure o conjunto de dados inserindo um nome, selecionando o índice e especificando o campo de carimbo de data/hora.  
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/datasets-configure-logs.png)

1. Escolha **Criar conjunto de dados** para salvar a configuração.

## Para criar um conjunto de dados de rastreamentos
<a name="observability-datasets-create-traces"></a>

Conclua as etapas a seguir para criar um conjunto de dados de rastreamentos na OpenSearch interface do usuário.

1. **Em seu espaço de trabalho de observabilidade, expanda **Discover** no painel de navegação à esquerda e escolha Traços.**

1. Escolha **Criar conjunto de dados**.

1. Selecione uma fonte de dados na lista de conexões de OpenSearch serviço disponíveis.

1. Configure o conjunto de dados inserindo um nome, selecionando o índice de extensão e especificando o campo de carimbo de data/hora.  
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/datasets-configure-traces.png)

1. Escolha **Criar conjunto de dados** para salvar a configuração.

## Para visualizar conjuntos de dados
<a name="observability-datasets-view"></a>

Você pode visualizar todos os conjuntos de dados configurados no seletor de conjuntos de dados na página Discover Logs ou Discover Traces. A lista de conjuntos de dados mostra o nome, o tipo, a fonte de dados e o campo de carimbo de data/hora de cada conjunto de dados.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/datasets-list.png)


## Analisando conjuntos de dados no Discover
<a name="observability-datasets-analyze"></a>

Depois de criar um conjunto de dados, você pode analisá-lo na página Discover correspondente.

### Logs
<a name="observability-datasets-analyze-logs"></a>

Selecione um conjunto de dados de registros no seletor de conjuntos de dados na página Descobrir registros para consultar e visualizar seus dados de registro usando PPL. Para obter mais informações, consulte [Descubra registros](observability-analyze-logs.md).

### Rastreamentos
<a name="observability-datasets-analyze-traces"></a>

Selecione um conjunto de dados de rastreamentos no seletor de conjuntos de dados na página Descobrir traços para explorar extensões de rastreamento, visualizar métricas RED e detalhar traços individuais. Para obter mais informações, consulte [Descubra traços](observability-analyze-traces.md).

# Descubra registros
<a name="observability-analyze-logs"></a>

A página Discover Logs fornece uma interface dedicada para explorar e analisar dados de log em seu espaço de trabalho OpenSearch de observabilidade do Service. Você pode escrever consultas PPL para filtrar e agregar dados de log, criar visualizações diretamente dos resultados da consulta e adicionar essas visualizações aos painéis. A página também fornece assistência de consulta em linguagem natural fornecida pelo assistente de OpenSearch IA.

## Para acessar a página de registros
<a name="observability-logs-access"></a>

**Em seu espaço de trabalho de observabilidade, expanda **Discover** no painel de navegação à esquerda e escolha Registros.**

## Explorando dados de log
<a name="observability-logs-explore"></a>

A interface Discover Logs fornece os seguintes componentes para explorar seus dados de registro.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-logs/discover-logs-interface.png)

+ **Seletor de conjunto** de dados — escolha o conjunto de dados de registros que você deseja consultar. Cada conjunto de dados é mapeado para um ou mais índices em seu domínio de OpenSearch serviço.
+ **Editor de consultas** — escreva consultas PPL para filtrar, agregar e transformar seus dados de registro. O editor fornece sugestões de preenchimento automático e destaque de sintaxe.
+ **Filtro de tempo** — especifique o intervalo de tempo para os resultados da consulta. Você pode escolher um intervalo relativo ou especificar horários absolutos de início e término.
+ **Painel de resultados** — Visualize os resultados da consulta como uma tabela de eventos de log. Você pode expandir eventos individuais para ver todos os campos.
+ **Histograma** — Visualize a distribuição dos eventos de log ao longo do tempo. O histograma é atualizado automaticamente com base na sua consulta e no filtro de tempo.
+ **Painel de campos** — Navegue pelos campos disponíveis em seu conjunto de dados e adicione-os como colunas à tabela de resultados.

## Consultando registros usando PPL
<a name="observability-logs-query-ppl"></a>

A linguagem de processamento canalizada (PPL) é uma linguagem de consulta que usa a sintaxe baseada em pipe (`|`) para encadear comandos. Você pode usar o PPL para filtrar, agregar e transformar seus dados de log.

### Consultas básicas
<a name="observability-logs-basic-queries"></a>

Para recuperar todos os eventos de log de um conjunto de dados, use o `source` comando:

```
source = my-logs-dataset
```

Para limitar o número de resultados, use o `head` comando:

```
source = my-logs-dataset | head 20
```

### Filtrando com WHERE
<a name="observability-logs-where-clause"></a>

Use a `where` cláusula para filtrar eventos de log com base nos valores do campo:

```
source = my-logs-dataset | where severity_text = 'ERROR'
```

Você pode combinar várias condições:

```
source = my-logs-dataset |
    where severity_text = 'ERROR' and service_name = 'payment-service'
```

### Gerenciando consultas
<a name="observability-logs-manage-queries"></a>

Você pode salvar as consultas usadas com frequência para reutilização. Para salvar uma consulta, escolha **Salvar** na barra de ferramentas do editor de consultas e insira um nome para a consulta. Para carregar uma consulta salva, escolha **Abrir** e selecione a consulta na lista.

Para obter a lista completa de comandos e funções do PPL, consulte a referência da [linguagem de processamento canalizado](https://observability.opensearch.org/docs/ppl/).

## Criação de visualizações a partir de registros
<a name="observability-logs-visualizations"></a>

Você pode criar visualizações diretamente dos resultados da sua consulta PPL. Use o `stats` comando para agregar dados para visualização:

```
source = my-logs-dataset |
    stats count() as error_count by service_name, span(timestamp, 1h)
```

Depois de executar uma `stats` consulta, escolha a guia **Visualização** para ver os resultados como um gráfico.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-logs/discover-logs-visualization.png)


### Tipos de visualização
<a name="observability-logs-viz-types"></a>

A tabela a seguir descreve os tipos de visualização que você pode usar.


| Tipo | Description | 
| --- | --- | 
| Linha | Exibe pontos de dados conectados por linhas, úteis para mostrar tendências ao longo do tempo. | 
| Área | Semelhante a um gráfico de linhas com a área abaixo da linha preenchida, útil para mostrar o volume ao longo do tempo. | 
| Barra | Exibe dados como barras verticais ou horizontais, úteis para comparar valores entre categorias. | 
| Métrica | Exibe um único valor numérico, útil para mostrar os principais indicadores de desempenho. | 
| Linha do tempo dos estados | Exibe as mudanças de estado ao longo do tempo como faixas coloridas, úteis para monitorar as transições de status. | 
| Mapa de calor | Exibe dados como uma matriz de células coloridas, útil para mostrar densidade e padrões. | 
| Medidor em barras | Exibe um único valor como uma barra preenchida dentro de um intervalo, útil para mostrar o progresso em direção a um limite. | 
| Pizza | Exibe dados como fatias proporcionais de um círculo, úteis para mostrar a composição. | 

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-logs/discover-logs-viz-types.png)


### Configurações de visualização
<a name="observability-logs-viz-settings"></a>

Quando a guia **Visualização** está ativa, um painel de configurações aparece no lado direito da tela. Use esse painel para configurar o tipo de gráfico, mapear campos em eixos e personalizar estilos visuais, como cores e legendas.

Para alternar os eixos de uma visualização, use a configuração do eixo no painel de configurações.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-logs/discover-logs-switch-axes.png)


## Adicionar visualizações aos painéis
<a name="observability-logs-add-to-dashboard"></a>

Depois de criar uma visualização, você pode adicioná-la a um painel para monitoramento contínuo. Escolha **Salvar no painel** na barra de ferramentas de visualização e selecione um painel existente ou crie um novo. A visualização é salva com sua consulta PPL subjacente para que seja atualizada automaticamente quando você abre o painel.

# Descubra traços
<a name="observability-analyze-traces"></a>

A página Discover Traces fornece uma interface dedicada para explorar dados de rastreamento distribuídos em seu espaço de trabalho OpenSearch de observabilidade do Service. Você pode visualizar as métricas RED (taxa, taxa de erro, duração) de seus serviços, pesquisar extensões de rastreamento com filtragem facetada e detalhar extensões e rastreamentos individuais para diagnosticar problemas de desempenho. A página também oferece suporte à correlação de rastreamentos com dados de registro relacionados.

## Para acessar a página Traces
<a name="observability-traces-access"></a>

**Em seu espaço de trabalho de observabilidade, expanda **Discover** no painel de navegação à esquerda e escolha Traços.**

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-traces/discover-traces.png)


## Configurando conjuntos de dados de rastreamento
<a name="observability-traces-configure-datasets"></a>

Antes de explorar os dados de rastreamento, você deve configurar um conjunto de dados de rastreamentos. Você pode criar um conjunto de dados automática ou manualmente.

### Criação automática de conjuntos de dados
<a name="observability-traces-auto-create"></a>

Quando você navega até a página Descobrir Traços pela primeira vez e os dados de rastreamento existem em seu domínio, a página solicita que você crie um conjunto de dados automaticamente. Escolha **Criar conjunto de dados** para aceitar a configuração padrão.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-traces/trace-auto-create.png)


### Criação manual do conjunto de dados
<a name="observability-traces-manual-create"></a>

Para criar manualmente um conjunto de dados de rastreamentos, siga as etapas em[Para criar um conjunto de dados de rastreamentos](observability-datasets.md#observability-datasets-create-traces). A criação manual permite que você controle o padrão do índice, o campo de carimbo de data/hora e o nome do conjunto de dados.

## Exploração de dados de rastreamento
<a name="observability-traces-explore"></a>

A página Descobrir Traços fornece os seguintes componentes para explorar seus dados de rastreamento.
+ **Métricas RED** — Taxa de visualização (solicitações por segundo), taxa de erro (porcentagem de solicitações com falha) e duração (percentis de latência) do conjunto de dados selecionado. Essas métricas são atualizadas com base no seu filtro de tempo.
+ **Campos facetados** — filtre extensões de rastreamento por nome de serviço, operação, código de status e outros atributos de extensão. Selecione valores no painel de campos facetados para restringir seus resultados.
+ **Tabela de extensão** — Procure extensões individuais com colunas para ID de rastreamento, ID de extensão, nome do serviço, operação, duração e status. Você pode classificar por qualquer coluna e expandir as linhas para ver os detalhes da extensão.

## Visualizando um período específico
<a name="observability-traces-view-span"></a>

Para ver os detalhes de um período específico, escolha a linha do intervalo na tabela do intervalo. Um painel suspenso é aberto com os atributos de extensão, atributos de recursos e informações do evento.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-traces/trace-details-flyout.png)


## Página de detalhes do rastreamento
<a name="observability-traces-detail-page"></a>

Para visualizar o traçado completo, escolha o link do ID do rastreamento na tabela de extensão ou no painel suspenso. A página de detalhes do traçado exibe um gráfico em cascata mostrando todas as extensões do traçado, suas relações temporais e a duração geral do traçado. Você pode expandir extensões individuais para visualizar seus atributos e identificar gargalos.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-traces/trace-detail-page.png)


## Correlacionando traços com registros
<a name="observability-traces-correlate-logs"></a>

Ao configurar uma correlação entre um conjunto de dados de rastreamentos e um conjunto de dados de registros, você pode visualizar entradas de registro relacionadas diretamente na página Discover Traces. Para obter informações sobre a criação de correlações, consulte[Correlações](observability-correlations.md).

### Visualizando registros relacionados
<a name="observability-traces-related-logs"></a>

No menu suspenso de detalhes do intervalo ou na página de detalhes do rastreamento, escolha a guia **Registros relacionados** para visualizar as entradas de registro que correspondam ao ID de rastreamento, ao nome do serviço e ao intervalo de tempo do intervalo. Essa correlação ajuda você a entender o que aconteceu em seu aplicativo durante a execução do período.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-traces/related-logs.png)


### Redirecionamento de log com contexto
<a name="observability-traces-log-redirection"></a>

Você pode navegar de uma extensão de rastreamento diretamente para a página Discover Logs com o contexto relevante preservado. Escolha **Exibir em registros no** painel de registros relacionados para abrir a página Descobrir registros com a consulta pré-preenchida para filtrar pelo ID de rastreamento e intervalo de tempo do período.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/discover-traces/logs-redirection.png)


## Consultando rastreamentos usando PPL
<a name="observability-traces-querying"></a>

Você pode usar o PPL para consultar dados de rastreamento diretamente. O PPL encadeia comandos usando o caractere pipe para filtrar, transformar e agregar dados de amplitude.

O exemplo a seguir encontra os 10 rastreamentos mais lentos:

```
source = otel-v1-apm-span-*
| where durationInNanos > 5000000000
| fields traceId, serviceName, name, durationInNanos
| sort - durationInNanos
| head 10
```

O exemplo a seguir conta os erros por serviço:

```
source = otel-v1-apm-span-*
| where status.code = 2
| stats count() as errorCount by serviceName
| sort - errorCount
```

O exemplo a seguir encontra rastreamentos para um serviço específico:

```
source = otel-v1-apm-span-*
| where serviceName = 'checkout-service'
| where parentSpanId = ''
| sort - startTime
| head 20
```

# Metrics
<a name="observability-metrics"></a>

A página Discover Metrics na OpenSearch interface do usuário fornece uma interface dedicada para descobrir, consultar e visualizar dados métricos de séries temporais. Esta página foi otimizada para trabalhar com as métricas do Prometheus usando o PromQL.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/dashboards/prometheus.png)


A página Discover Metrics está disponível nos espaços de trabalho do Observability. **Para acessá-lo, navegue até um espaço de trabalho do Observability, expanda **Discover** no painel de navegação à esquerda e selecione Métricas.**

## Configurando uma fonte de dados do Prometheus
<a name="observability-metrics-data-source"></a>

Antes de começar, configure uma fonte de dados do Prometheus usando um dos seguintes métodos:
+ [Criação de uma fonte de dados do Amazon Managed Service para Prometheus](direct-query-prometheus-creating.md)no console AWS de gerenciamento
+ [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/opensearch/add-direct-query-data-source.html)

## Painel de consulta
<a name="observability-metrics-query"></a>

Você pode escrever e executar consultas métricas no painel de consultas na parte superior da página Descobrir métricas. O editor de consultas fornece sugestões de preenchimento automático e destaque de sintaxe para o PromQL.

**Escrevendo consultas**  
Escreva consultas usando a sintaxe PromQL. Por exemplo:

```
up{job="prometheus"}
```

**Executar consultas**  
Para executar uma consulta, insira sua consulta no editor de consultas e selecione **Atualizar.**

Você pode executar várias consultas PromQL juntas separando-as com ponto e vírgula (): `;`

```
up{job="prometheus"};
node_cpu_seconds_total{mode="idle"};
```

Cada consulta é executada de forma independente e os resultados são combinados na saída.

## Filtro de tempo
<a name="observability-metrics-time-filter"></a>

Use o filtro de tempo para especificar o intervalo de tempo para seus dados métricos:
+ **Seleção rápida** — Escolha um intervalo de tempo relativo (por exemplo, os últimos 15 minutos ou a última 1 hora).
+ **Comumente usado** — Selecione entre intervalos de tempo predefinidos.
+ **Personalizado** — Especifique os horários absolutos de início e término.
+ **Atualização automática** — Defina um intervalo de atualização automática.

## Visualização de resultados
<a name="observability-metrics-results"></a>

Depois de executar uma consulta, os resultados são exibidos em uma interface com guias:
+ **Métricas** — Exibe o ponto de dados mais recente de cada série em formato de tabela.
+ **Raw** — Mostra o ponto de dados mais recente de cada série como JSON bruto retornado pela fonte de dados.
+ **Visualização** — fornece gráficos interativos para seus dados métricos.

## Configurando visualizações
<a name="observability-metrics-visualizations"></a>

Quando a guia **Visualização** é selecionada, um painel de configurações aparece no lado direito da tela. Use esse painel para:
+ **Selecione um tipo de gráfico** — Escolha entre visualizações de linha, barra, pizza, medidor ou tabela.
+ **Eixos do mapa** — Atribua campos aos eixos X e Y.
+ **Personalize estilos** — ajuste cores, legendas, linhas de grade e outras opções visuais.

Quando você modifica as configurações, a visualização é atualizada automaticamente.

# Correlações
<a name="observability-correlations"></a>

As correlações vinculam um conjunto de dados de rastreamentos a um conjunto de dados de registros para que você possa visualizar as entradas de registro relacionadas ao investigar extensões de rastreamento. Ao definir uma correlação, você ativa a página Discover Traces para exibir registros que ocorreram durante a execução de um período, ajudando você a diagnosticar problemas mais rapidamente sem alternar entre as páginas.

## Requisitos de correlação
<a name="observability-correlations-requirements"></a>

Para criar uma correlação, seus dados de registro e rastreamento devem conter campos correspondentes. A tabela a seguir descreve os campos que a correlação usa para unir dados de rastreamento e registro.


| Campo | Description | Obrigatório | 
| --- | --- | --- | 
| ID de rastreamento | O identificador exclusivo do rastreamento. Deve existir tanto no índice de extensão de rastreamento quanto no índice de log. | Sim | 
| ID do período | O identificador exclusivo do período. Usado para combinar os registros com um intervalo específico em um rastreamento. | Não | 
| Nome do serviço | O nome do serviço que gerou a telemetria. Usado para filtrar registros relacionados por serviço. | Não | 
| Timestamp | O campo de hora usado para definir o escopo dos registros relacionados ao intervalo de tempo do período. | Sim | 

## Para criar uma trace-to-logs correlação
<a name="observability-correlations-create"></a>

Conclua as etapas a seguir para criar uma correlação entre um conjunto de dados de rastreamentos e um conjunto de dados de registros.

1. **Em seu espaço de trabalho de observabilidade, expanda **Discover** no painel de navegação à esquerda e escolha Traços.**

1. Selecione o conjunto de dados de rastreamentos que você deseja correlacionar.

1. Escolha a guia **Correlações** no painel de configuração do conjunto de dados.  
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/correlations-trace-dataset-tab.png)

1. Escolha **Criar correlação**.

1. Na caixa de diálogo de configuração, selecione o conjunto de dados de registros de destino e mapeie os campos de correlação necessários (ID de rastreamento e registro de data e hora). Opcionalmente, mapeie o ID do período e o nome do serviço para obter uma correspondência mais precisa.  
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/correlations-configure-dialog.png)

1. Escolha **Criar** para salvar a correlação.

1. Verifique se a correlação aparece na tabela de correlações.  
![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/correlations-created-table.png)

## Visualização de correlações em conjuntos de dados de registros
<a name="observability-correlations-view-logs"></a>

Depois de criar uma correlação, você também pode visualizá-la do lado do conjunto de dados de registros. Navegue até a página Descobrir registros, selecione o conjunto de dados de registros correlacionados e escolha a guia **Correlações** para ver o conjunto de dados de rastreamentos vinculados.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/correlations-logs-dataset-tab.png)


## Usando correlações na página Traces
<a name="observability-correlations-use-traces"></a>

Quando existe uma correlação, a página Discover Traces exibe registros relacionados na visualização de detalhes do intervalo. Escolha um intervalo na tabela de intervalos para abrir o menu suspenso de detalhes e, em seguida, escolha a guia **Registros relacionados** para visualizar as entradas de registro correlacionadas.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/datasets/correlations-span-details-logs.png)


## Gerenciando correlações
<a name="observability-correlations-manage"></a>

Você pode editar ou remover correlações da guia **Correlações** do conjunto de dados de rastreamentos ou registros.
+ **Edição** — Escolha a correlação na tabela e escolha **Editar** para atualizar os mapeamentos de campo ou o conjunto de dados de destino.
+ **Removendo** — Escolha a correlação na tabela e escolha **Excluir** para remover a correlação. A remoção de uma correlação não exclui nenhum dado.

# Painéis
<a name="observability-dashboards"></a>

Os painéis combinam visualizações de registros, rastreamentos e métricas em uma única visualização. Você pode usar painéis para monitorar a integridade operacional, responder a incidentes e monitorar a utilização de recursos em seu sistema distribuído.

A tabela a seguir descreve casos de uso comuns para painéis.


| Caso de uso | Exemplo | 
| --- | --- | 
| Monitoramento operacional | Acompanhe a integridade do serviço, a taxa de transferência e as taxas de erro em tempo real. | 
| Resposta a incidentes | Correlacione registros, rastreamentos e métricas durante um incidente ativo. | 
| Planejamento de capacidade | Monitore as tendências de utilização de recursos para planejar a escalabilidade. | 
| Acompanhamento de disponibilidade | Avalie o tempo de atividade e a disponibilidade em relação aos objetivos de nível de serviço. | 
| Análise pós-incidente | Analise dados históricos para entender a causa raiz de incidentes anteriores. | 

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/otel-dashboard.png)


## Estrutura do painel
<a name="observability-dashboards-structure"></a>

Um painel é uma coleção de painéis dispostos em uma grade. Cada painel consiste nos seguintes componentes.
+ **Fonte de dados** — O OpenSearch índice ou a fonte de dados do Amazon Managed Service for Prometheus que o painel consulta.
+ **Consulta — Uma consulta** PPL ou PromQL que recupera os dados para o painel.
+ **Tipo de visualização** — O tipo de gráfico usado para renderizar os resultados da consulta, como linha, barra ou valor métrico.
+ **Configuração opcional** — eixos, legendas, limites e opções de formatação.

O seletor de intervalo de tempo na parte superior do painel se aplica a todos os painéis. Você pode substituir o intervalo de tempo para painéis individuais quando necessário.

## Criação de painéis a partir do Discover
<a name="observability-dashboards-discover"></a>

O fluxo de trabalho recomendado para criar painéis começa no Discover. Esse fluxo de trabalho é consistente em todos os registros, rastreamentos e métricas.

1. **Consulte seus dados no Discover** — Navegue até Discover Logs, Discover Traces ou Discover Metrics e escreva uma consulta usando PPL (para registros e rastreamentos) ou ProMQL (para métricas).

1. **Crie uma visualização** — Quando sua consulta retornar resultados, use a guia de visualização para escolher um tipo de gráfico e configurar a exibição. Para consultas de registro e rastreamento, comandos de agregação, como alternar `stats` automaticamente para a visualização de visualização.

1. **Salvar em um painel** — Escolha **Adicionar ao painel** para salvar a visualização em um painel novo ou existente. O painel permanece ativo, sendo atualizado à medida que novos dados chegam.

1. **Iterar** — repita o procedimento para cada pergunta que você deseja que o painel responda. Quando algo parece errado em um painel, escolha qualquer painel para abrir a consulta subjacente no Discover para uma investigação mais aprofundada.

**Importante**  
As visualizações criadas por meio da página **Visualizações** na OpenSearch interface do usuário usam DQL (Dashboards Query Language) e DSL (Domain Specific Language), que não oferecem suporte à Piped Processing Language (PPL) no momento. Para criar visualizações baseadas em PPL, use o fluxo de trabalho Discover descrito acima.

## Filtros do painel
<a name="observability-dashboards-filters"></a>

Os filtros permitem restringir os dados exibidos em todos os painéis em um painel sem editar consultas individuais.

**Para adicionar um filtro**

1. Abra o painel que você deseja filtrar.

1. Escolha **Adicionar filtro** na barra de filtros.

1. Selecione um nome de campo na lista suspensa.

1. Selecione um operador e insira um valor.

1. Escolha **Salvar**.

A tabela a seguir descreve casos comuns de uso de filtros.


| Cenário | Campo | Operador | Valor | 
| --- | --- | --- | --- | 
| Visualize um único ambiente | environment | is | production | 
| Erros isolados | status\$1code | is greater than or equal to | 400 | 
| Concentre-se em um serviço específico | service.name | is | order-service | 
| Excluir verificações de saúde | http.url | is not | /health | 

Filtros **fixados em comparação com filtros não fixados** — Um filtro fixo persiste quando você navega entre painéis. Um filtro não fixado se aplica somente ao painel atual. Para fixar um filtro, escolha o ícone de alfinete ao lado do selo do filtro.

## Criar dashboards
<a name="observability-dashboards-build"></a>

### Tipos de visualização
<a name="observability-dashboards-build-viz-types"></a>

A tabela a seguir descreve os tipos de visualização disponíveis para painéis de painel.


| Tipo | Caso de uso | 
| --- | --- | 
| Linha | Tendências ao longo do tempo, como taxas de solicitação ou latência | 
| Área | Volume ao longo do tempo com detalhamentos acumulados | 
| Barra | Comparando valores entre categorias | 
| Barra horizontal | Comparações classificadas, como os principais serviços por contagem de erros | 
| Tabela de dados | Dados tabulares com classificação e paginação | 
| Valor da métrica | Indicadores de desempenho chave únicos, como o total de solicitações | 
| Medidor | Progresso em direção a um limite, como a utilização da CPU | 
| Pizza | Composição e proporções, como tráfego por região | 
| Mapa de calor | Padrões de densidade e distribuição em duas dimensões | 
| Nuvem de tags | Frequência relativa de termos, como mensagens de erro comuns | 

### Configurando painéis
<a name="observability-dashboards-build-configure"></a>

Cada painel tem um editor de consultas onde você escreve consultas PPL ou PromQL. Os exemplos a seguir mostram consultas comuns em painéis.

Contagem de erros por serviço (PPL):

```
source = logs-dataset |
    where severity_text = 'ERROR' |
    stats count() as error_count by service_name, span(timestamp, 5m)
```

Taxa de utilização da CPU (PromQL):

```
rate(container_cpu_usage_seconds_total{namespace="production"}[5m])
```

Você também pode configurar as seguintes opções do painel.
+ **Eixos** — Defina rótulos de eixos, escalas (lineares ou logarítmicas) e faixas de valores.
+ **Legendas** — Controle a posição da legenda e quais séries exibir.
+ **Limites** — Adicione linhas de limite horizontais para destacar os níveis críticos ou de aviso.

### Dicas de layout
<a name="observability-dashboards-build-layout"></a>

Use as dicas a seguir para organizar seus painéis de controle de forma eficaz.
+ Coloque painéis de resumo de alto nível (valores métricos, medidores) na parte superior do painel.
+ Agrupe painéis relacionados, como todos os painéis para um único serviço.
+ Use larguras consistentes para painéis na mesma linha.
+ Arraste as bordas do painel para redimensionar e arraste os cabeçalhos do painel para reposicionar.

### Layouts recomendados
<a name="observability-dashboards-build-recommended"></a>

As tabelas a seguir descrevem os layouts de painel recomendados para tipos comuns de painéis.

**Painel de integridade do serviço**


| Painel | Tipo de visualização | 
| --- | --- | 
| Taxa de solicitação | Linha | 
| Taxa de erro | Linha | 
| Latência P99 | Linha | 
| Alertas ativos | Valor da métrica | 
| Principais erros por serviço | Barra horizontal | 

**Painel de resposta a incidentes**


| Painel | Tipo de visualização | 
| --- | --- | 
| Logs de erro | Tabela de dados | 
| Contagem de erros ao longo do tempo | Área | 
| Serviços afetados | Pizza | 
| Picos de latência | Linha | 

**Painel de utilização de recursos**


| Painel | Tipo de visualização | 
| --- | --- | 
| Utilização da CPU | Medidor | 
| Uso de memória ao longo do tempo | Área | 
| E/S de disco | Linha | 
| Throughput na rede | Linha | 

### Controles de intervalo de tempo
<a name="observability-dashboards-build-time-range"></a>

O seletor de intervalo de tempo na parte superior do painel controla a janela de tempo de todos os painéis. Você pode selecionar um intervalo predefinido (como **Últimos 15 minutos** ou **Últimas 24 horas**) ou especificar um intervalo absoluto personalizado.

Para ativar a atualização automática, escolha a lista suspensa do intervalo de atualização ao lado do seletor de intervalo de tempo e selecione um intervalo. A atualização automática executa novamente todas as consultas do painel no intervalo especificado para que seu painel exiba os dados mais recentes.

## Compartilhar painéis
<a name="observability-dashboards-sharing"></a>

Você pode compartilhar painéis com outros usuários em sua organização por meio URLs de instantâneos e exportações.

### Compartilhe por meio de URL
<a name="observability-dashboards-sharing-url"></a>

Copie o URL do painel da barra de endereço do seu navegador e compartilhe-o diretamente. O URL preserva o intervalo de tempo e os filtros atuais. Você pode incluir links do painel em marcadores, runbooks ou documentação de resposta a incidentes.

### Snapshots
<a name="observability-dashboards-sharing-snapshots"></a>

Um instantâneo captura o estado atual de um painel, incluindo todos os dados do painel, em um momento específico. Os instantâneos são somente para leitura e não são atualizados quando os dados subjacentes são alterados. Use instantâneos para preservar um registro do estado do painel durante incidentes ou revisões.

### Definições de importação e exportação
<a name="observability-dashboards-sharing-import-export"></a>

Você pode exportar uma definição de painel como JSON e importá-la para outro espaço de trabalho ou ambiente. Essa abordagem é útil para promover painéis do desenvolvimento à produção ou compartilhar layouts padrão entre equipes.

### Práticas recomendadas para compartilhamento
<a name="observability-dashboards-sharing-best-practices"></a>
+ **Público** — Crie painéis para um público específico, como engenheiros de plantão ou liderança.
+ **Foco** — limite cada painel a uma única finalidade ou fluxo de trabalho.
+ **Convenções — Use convenções** de nomenclatura consistentes para painéis e painéis em toda a sua organização.
+ **Controle de versão** — Exporte as definições JSON do painel e armazene-as no controle de versão para acompanhar as alterações ao longo do tempo.

## Solucionar problemas nos dashboards
<a name="observability-dashboards-troubleshooting"></a>

Esta seção descreve problemas comuns do painel e como resolvê-los.

### Sem dados em um painel
<a name="observability-dashboards-troubleshooting-no-data"></a>

Se um painel não exibir dados, verifique as seguintes causas comuns.


| Causa | Verificar | Correção | 
| --- | --- | --- | 
| Intervalo de tempo muito estreito | Verifique se o intervalo de tempo do painel cobre o período em que os dados foram ingeridos. | Expanda o intervalo de tempo ou selecione Últimas 24 horas. | 
| Filtro ativo excluindo dados | Examine a barra de filtros para ver se há filtros que possam excluir todos os documentos correspondentes. | Remova ou ajuste o filtro e verifique se os dados aparecem. | 
| Padrão de índice incorreto | Confirme se a fonte de dados do painel aponta para um índice que contém dados. | Atualize a fonte de dados para o padrão de índice correto no editor de painéis. | 
| Erro de sintaxe de consulta | Procure mensagens de erro no cabeçalho do painel ou no editor de consultas. | Corrija a sintaxe PPL ou PromQL e execute novamente a consulta. | 

### Dados incorretos em um painel
<a name="observability-dashboards-troubleshooting-wrong-data"></a>

Se um painel exibir resultados inesperados, tente as etapas a seguir.
+ Verifique se a consulta retorna os campos esperados executando-a primeiro no Discover.
+ Verifique se o tipo de visualização corresponde à forma dos dados (por exemplo, use um gráfico de linhas para dados de séries temporais).
+ Confirme se a fonte de dados correta está selecionada no editor do painel.

### Dados obsoletos
<a name="observability-dashboards-troubleshooting-stale-data"></a>

Se os painéis do painel exibirem informações desatualizadas, tente as etapas a seguir.
+ Escolha o ícone de atualização na barra de ferramentas para atualizar manualmente todos os painéis.
+ Verifique se a atualização automática está ativada e definida para um intervalo apropriado.
+ Confirme se seu pipeline de ingestão está enviando dados ativamente para os índices configurados.

### Problemas de performance
<a name="observability-dashboards-troubleshooting-performance"></a>

As dicas a seguir podem ajudá-lo a resolver problemas comuns de desempenho.
+ **Painel lento** — reduza o número de painéis ou reduza o intervalo de tempo. Painéis com muitos painéis executam várias consultas simultaneamente, o que pode aumentar o tempo de carregamento.
+ **Painel lento** — Simplifique a consulta do painel. Evite usar padrões curinga em `where` cláusulas PPL e limite o número de compartimentos de agregação.
+ **Atraso do navegador** — reduza a densidade de dados nas visualizações. Por exemplo, aumente o intervalo de tempo nos `stats` comandos para produzir menos pontos de dados.

### Problemas de filtro
<a name="observability-dashboards-troubleshooting-filters"></a>

Se os filtros não se comportarem conforme o esperado, tente as etapas a seguir.
+ Verifique se o nome do campo no filtro corresponde ao nome do campo no mapeamento do índice.
+ Verifique se um filtro fixado de outro painel está afetando os resultados.
+ Remova todos os filtros e adicione-os novamente, um de cada vez, para isolar o problema.

### Inspecionar um painel
<a name="observability-dashboards-troubleshooting-inspect"></a>

O inspetor do painel ajuda você a depurar dados e problemas de consulta. **Para abrir o inspetor, escolha o menu do painel (três pontos) e selecione Inspecionar.** O inspetor fornece as seguintes guias.
+ **Dados** — Exibe os dados brutos retornados pela consulta em formato tabular.
+ **Solicitação** — Mostra a consulta enviada à fonte de dados, incluindo a instrução PPL ou ProMQL completa.
+ **Resposta** — Mostra a resposta bruta da fonte de dados, incluindo informações de tempo e status.

### Ferramentas para desenvolvedores de navegadores
<a name="observability-dashboards-troubleshooting-browser"></a>

Para solucionar problemas avançados, use as ferramentas de desenvolvedor do seu navegador para inspecionar as solicitações de rede. Abra a guia **Rede**, filtre as chamadas de API e procure solicitações com falha ou respostas lentas. Verifique se há mensagens de erro no corpo da resposta que possam ajudá-lo a identificar a causa raiz.

# Monitoramento de aplicações
<a name="observability-app-monitoring"></a>

O monitoramento de aplicativos fornece uma visão em tempo real do desempenho de seus serviços. Ele combina dados de topologia armazenados OpenSearch com métricas RED de séries temporais (taxa, erros, duração) do Amazon Managed Service for Prometheus para revelar informações de integridade, latência, taxa de transferência e erro em seu sistema distribuído.

Para acessar o monitoramento de aplicativos, na OpenSearch interface do usuário, navegue até **Observabilidade** > **Monitoramento de aplicativos**. A barra lateral mostra duas visualizações:
+ **Mapa de aplicativos** — Gráfico de topologia interativo das dependências do serviço
+ **Serviços** — Catálogo de todos os serviços instrumentados com filtragem, visualizações detalhadas e links de correlação

## Pré-requisitos
<a name="observability-app-monitoring-prereqs"></a>

Antes de usar o monitoramento de aplicativos, você deve ter os seguintes recursos configurados.
+ [Dados de rastreamento OTLP que fluem de seus OTel coletores para a OpenSearch ingestão](observability-ingestion.md) (métricas e registros são opcionais)
+ [Amazon Managed Service para Prometheus configurado para receber gravação remota do Inestion OpenSearch ](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/configure-client-prometheus.html)
+ Um espaço de trabalho de OpenSearch interface do usuário com a Observabilidade ativada

## Como funciona
<a name="observability-app-monitoring-how-it-works"></a>

O diagrama a seguir mostra a end-to-end arquitetura do monitoramento de aplicativos.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/otel-sdk-service.png)


1. Seus aplicativos e infraestrutura emitem telemetria por meio OpenTelemetry SDKs de instrumentação automática ou da API para o Collector. OTel OTel

1. O OTel coletor encaminha os dados de rastreamento para OpenSearch ingestão via OTLP.

1. O `otel_apm_service_map` processador OpenSearch de ingestão extrai service-to-service relacionamentos e calcula as métricas RED.

1. A topologia e os dados brutos de rastreamento são indexados em. OpenSearch As métricas RED são exportadas para o Amazon Managed Service for Prometheus por meio de gravação remota.

1. OpenSearch A interface de usuário consulta os dois repositórios para renderizar o mapa do aplicativo, o catálogo de serviços e as visualizações de detalhes do serviço.

## Services
<a name="observability-app-services"></a>

A visualização Serviços fornece um catálogo centralizado de todos os serviços instrumentados, exibindo métricas RED (Taxa, Erros, Duração) em um piscar de olhos. Você pode usar essa visualização para identificar rapidamente serviços não íntegros e detalhar as visualizações detalhadas para uma análise mais profunda.

**Para acessar a visualização Serviços, navegue até o espaço de trabalho Observability na OpenSearch UI e escolha **APM** > Serviços.**

A página inicial dos Serviços exibe uma tabela de todos os serviços instrumentados junto com painéis de resumo. A imagem a seguir mostra a página inicial dos Serviços.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/services-home.png)


A tabela a seguir descreve as colunas na tabela de serviços.


| Coluna | Description | 
| --- | --- | 
| Nome do serviço | O nome do serviço instrumentado. | 
| Latência P99 | A latência do 99º percentil do serviço. | 
| Latência P90 | A latência do 90º percentil do serviço. | 
| Latência P50 | A latência do 50º percentil (mediana) do serviço. | 
| Total requests | O número total de solicitações processadas durante o intervalo de tempo selecionado. | 
| Taxa de falha | A proporção de solicitações malsucedidas em relação ao total de solicitações. | 
| Environment | O ambiente de implantação do serviço, como production oustaging. | 

A página inicial também inclui os seguintes painéis de resumo:
+ **Principais serviços por taxa de falhas** — Serviços com a maior porcentagem de respostas de 5xx.
+ **Principais caminhos de dependência por taxa de falha** — caminhos de Service-to-service dependência com as maiores taxas de falha.

Você pode filtrar a tabela de serviços usando os seguintes filtros:
+ **Ambiente** — Filtre por ambiente de implantação.
+ **Latência** — Filtre por faixa de latência.
+ **Taxa de transferência** — Filtre por faixa de taxa de transferência da solicitação.
+ **Taxa de falha** — Filtrar por faixa de taxa de falha.

### Visão geral do serviço
<a name="observability-app-services-overview"></a>

Para abrir a exibição de detalhes do serviço, selecione um nome de serviço na tabela de serviços. A guia Visão geral exibe blocos métricos e gráficos de séries temporais para o serviço selecionado.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/services-overview.png)


A guia Visão geral inclui os seguintes gráficos de séries temporais:
+ **Latência por dependências de serviço** — latência P50, P90 e P99 dividida por dependências posteriores.
+ **Solicitações por operações** — Volume de solicitações para cada operação do serviço.
+ **Disponibilidade por operações** — Porcentagem de respostas bem-sucedidas para cada operação.
+ **Taxa de falhas e taxa de erro por operações** — Porcentagem de respostas de 5xx e 4xx para cada operação.

### Operações
<a name="observability-app-services-operations"></a>

A guia Operações fornece um detalhamento por operação para o serviço selecionado. Você pode classificar a tabela por qualquer coluna para identificar operações problemáticas.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/service-operations.png)


A tabela a seguir descreve as colunas na tabela de operações.


| Coluna | Description | 
| --- | --- | 
| Nome da operação | O nome da operação. | 
| Latência P50/P90/P99 | A latência dos percentis 50, 90 e 99 da operação. | 
| Total requests | O número total de solicitações para a operação durante o intervalo de tempo selecionado. | 
| Taxa de erro | A porcentagem de solicitações que retornaram erros. | 
| Disponibilidade | A porcentagem de respostas bem-sucedidas para a operação. | 

### Dependências
<a name="observability-app-services-dependencies"></a>

A guia Dependências exibe os serviços downstream que o serviço selecionado chama.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/service-dependencies.png)


A tabela a seguir descreve as colunas na tabela de dependências.


| Coluna | Description | 
| --- | --- | 
| Serviço de dependência | O nome do serviço downstream. | 
| Operação remota | A operação solicitou o serviço downstream. | 
| Operações de serviço | As operações no serviço atual que chamam essa dependência. | 
| Latência P99/P90/P50 | A latência do 99º, 90º e 50º percentil para o caminho da dependência. | 
| Total requests | O número total de solicitações para a dependência durante o intervalo de tempo selecionado. | 
| Taxa de erro | A porcentagem de solicitações à dependência que retornaram erros. | 
| Disponibilidade | A porcentagem de respostas bem-sucedidas da dependência. | 

### Correlações
<a name="observability-app-services-correlations"></a>

A visualização detalhada do serviço fornece correlações contextuais que permitem que você navegue diretamente das métricas do serviço até os registros e rastreamentos relacionados. Você pode usar correlações para investigar a causa raiz de picos de latência ou aumentos na taxa de erro.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/service-span-correlations.png)


As seguintes opções de correlação estão disponíveis:
+ **Exibir rastreamentos relacionados** — Abre uma visualização de rastreamento filtrada para o serviço ou operação selecionada.
+ **Exibir registros relacionados** — Abre uma exibição de registro filtrada para o serviço ou operação selecionada.
+ **Filtrar por atributos** — restringe os resultados da correlação por atributos de amplitude específicos.

## Mapa do aplicativo
<a name="observability-app-map"></a>

O Application Map é uma visualização de topologia interativa que o OpenSearch Ingestion gera automaticamente a partir de seus dados de rastreamento usando o processador. `otel_apm_service_map` O mapa exibe os serviços como nós com bordas direcionais que mostram padrões de comunicação, sobrepostos às métricas RED (taxa, erros, duração).

**Para acessar o Mapa do Aplicativo, navegue até o espaço de trabalho do Observability na OpenSearch UI e escolha **APM** > Mapa do aplicativo.**

A imagem a seguir mostra o Mapa do Aplicativo.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/application-map.png)


O mapa exibe as seguintes métricas RED para cada serviço:
+ **Taxa** — Solicitações por segundo processadas pelo serviço.
+ **Erros** — Porcentagem de respostas 4xx e 5xx.
+ **Duração** — latência P50 e P99 para o serviço.

O `otel_apm_service_map` processador gera essas métricas e as armazena no Amazon Managed Service for Prometheus por meio de gravação remota.

A visualização da topologia representa os serviços como nós e a direção da comunicação como bordas. O código de cores indica o estado de saúde de cada serviço. O mapa é atualizado automaticamente à medida que o OpenSearch Ingestion ingere novos dados de rastreamento.

### Serviços de agrupamento
<a name="observability-app-map-groupby"></a>

Você pode agrupar serviços por atributos como linguagem de programação, equipe ou ambiente. Quando você seleciona um atributo agrupado por, o mapa muda de um gráfico de topologia para uma visualização em grade de cartões. Cada cartão representa um grupo de serviços que compartilham o mesmo valor de atributo.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/groupby-attributes.png)


Os atributos agrupados disponíveis são determinados pela `group_by_attributes` configuração do `otel_apm_service_map` processador em Ingestão. OpenSearch 

### Visualizando detalhes do nó
<a name="observability-app-map-node-details"></a>

Para ver detalhes de um serviço, selecione um nó no mapa. Um painel de detalhes é aberto com as seções a seguir.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/application-map-node-details.png)


A seção **Health** exibe as seguintes métricas resumidas:
+ Total Requests
+ Total de erros 4xx
+ Total de falhas 5xx

A seção **Métricas** exibe os seguintes gráficos de séries temporais:
+ Solicitações
+ Latência P50/P90/P99
+ Falhas 5xx
+ Erros 4xx

Escolha **Exibir detalhes** para navegar até a visualização detalhada dos serviços do serviço selecionado.

### Filtrando o mapa
<a name="observability-app-map-filters"></a>

Você pode filtrar o Mapa do Aplicativo usando os seguintes filtros:
+ **Taxa de falhas** — Filtre os serviços por taxa de falhas do lado do servidor (5xx).
+ **Taxa de erro** — Filtre os serviços por taxa de erro do lado do cliente (4xx).
+ **Ambiente** — Filtre os serviços por ambiente de implantação.

A imagem a seguir mostra o mapa filtrado pela taxa de erro.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/apm/filter-by-error-rate.png)


### Correlações contextuais
<a name="observability-app-map-correlations"></a>

Você pode navegar diretamente da visualização de topologia até os registros e rastreamentos relacionados. Em qualquer nó de serviço, as seguintes opções de correlação estão disponíveis:
+ **Exibir rastreamentos relacionados** — Abre uma visualização de rastreamento filtrada para o serviço selecionado.
+ **Exibir registros relacionados** — Abre uma exibição de registro filtrada para o serviço selecionado.

# Observabilidade da IA
<a name="observability-ai"></a>

A observabilidade da IA OpenSearch fornece end-to-end ferramentas para monitorar, depurar e otimizar fluxos de trabalho do agente de IA e do modelo de linguagem grande (LLM). Construído com base nas convenções semânticas do GenAI e integrado nativamente com OpenTelemetry (OTel), ele oferece visibilidade total de como seus aplicativos de IA se comportam na produção.

A observabilidade da IA inclui os seguintes recursos:
+ **Rastreamento de agentes — Capture rastreamentos** hierárquicos de execução nas etapas de orquestração do agente, chamadas de LLM, invocações de ferramentas e operações de recuperação.
+ **Convenções semânticas do GenAI** — Use OTel atributos padronizados como`gen_ai.system`, e `gen_ai.usage.input_tokens` para descrever a telemetria `gen_ai.request.model` específica de IA.
+ **Instrumentação automática** — Capture automaticamente traços de estruturas e fornecedores populares de IA, incluindo OpenAI, Anthropic, Amazon Bedrock LangChain e mais de 20 bibliotecas adicionais.
+ **Consulta PPL** — Consulte e agregue dados de rastreamento usando a Piped Processing Language (PPL) diretamente da interface do usuário. OpenSearch 

## Introdução
<a name="observability-ai-getting-started"></a>

Esta seção explica como instrumentar um agente de IA, enviar rastros para o Amazon OpenSearch Service e visualizá-los na OpenSearch interface do usuário.

### Para instalar o SDK
<a name="observability-ai-install-sdk"></a>

Instale o pacote de instrumentação OpenTelemetry GenAI:

```
pip install opentelemetry-instrumentation-openai-v2 opentelemetry-sdk opentelemetry-exporter-otlp
```

### Para instrumentar seu código de agente
<a name="observability-ai-instrument"></a>

O exemplo a seguir mostra como registrar o OTel SDK, anotar suas funções de agente com o `@observe` decorador e enriquecer extensões com atributos GenAI.

```
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

# Register the tracer provider
provider = TracerProvider()
processor = BatchSpanProcessor(
    OTLPSpanExporter(endpoint="<your-osis-endpoint>")  # Use your OpenSearch Ingestion endpoint with SigV4
)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

# Decorate your agent function
@observe
def run_agent(prompt: str):
    with tracer.start_as_current_span("invoke_agent") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        span.set_attribute("gen_ai.system", "openai")
        span.set_attribute("gen_ai.request.model", "gpt-4")

        # Enrich with token usage after the LLM call
        response = call_llm(prompt)
        span.set_attribute("gen_ai.usage.input_tokens", response.input_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", response.output_tokens)
        return response
```

**nota**  
Ao enviar rastreamentos para o Amazon OpenSearch Service, use seu endpoint de pipeline OpenSearch de ingestão com autenticação SigV4 em vez de um endpoint localhost. Para obter mais informações sobre como configurar pipelines OpenSearch de ingestão, consulte. [Visão geral da OpenSearch ingestão da Amazon](ingestion.md)

### Para visualizar traços na OpenSearch interface do usuário
<a name="observability-ai-view-traces"></a>

Depois que seu aplicativo instrumentado enviar dados de rastreamento, você poderá explorá-los na OpenSearch interface do usuário. Em seu espaço de trabalho de observabilidade, expanda **Discover** no painel de navegação à esquerda e escolha **Agent** Traces.

## UI de rastreamento de agentes
<a name="observability-ai-agent-tracing"></a>

A página Agent Traces na OpenSearch UI fornece uma interface específica para explorar, depurar e monitorar rastreamentos de execução do agente LLM. Ele oferece aos desenvolvedores e operadores de plataforma total observabilidade em aplicativos de IA agentes, incluindo visualizações hierárquicas de rastreamento, menus de detalhes, visualizações de fluxo e métricas agregadas.

### Arquitetura
<a name="observability-ai-architecture"></a>

O diagrama a seguir mostra o fluxo de dados dos aplicativos instrumentados para a interface do Agent Traces:

```
LLM Application (with OTel SDK + GenAI instrumentation)
    |
    |  OTLP (gRPC/HTTP)
    v
OTel Collector (batch, transform)
    |
    +---- OTLP ----> OpenSearch Ingestion --> OpenSearch (otel-v1-apm-span-*)
    |
    +---- Prometheus Remote Write --> Prometheus (metrics)
                                          |
                                          v
                              OpenSearch UI
                              +-- Agent Traces Plugin
```

### Pré-requisitos
<a name="observability-ai-prereqs"></a>

Antes de usar o Agent Traces, verifique se você tem o seguinte:
+ Um OpenSearch cluster com dados de rastreamento indexados em `otel-v1-apm-span-*` índices.
+ OpenTelemetry instrumentação com convenções semânticas GenAI habilitadas em seu aplicativo LLM.
+ OpenSearch Ingestão configurada com o `otel_trace_raw` processador para o qual a ingestão se estende. OpenSearch
+ Suporte a consultas PPL habilitado na OpenSearch interface do usuário.

### Atributos de extensão necessários
<a name="observability-ai-span-attributes"></a>

O Agent Traces exige atributos de amplitude específicos para renderizar os dados de rastreamento corretamente. As tabelas a seguir descrevem os campos principais e os atributos específicos do Genai.

**Campos de extensão principal**  
Cada período deve incluir os seguintes campos principais:


| Campo | Tipo | Description | 
| --- | --- | --- | 
| traceId | String | Identificador exclusivo para todo o rastreamento. | 
| spanId | String | Identificador exclusivo para esse período. | 
| parentSpanId | String | Identificador do período principal. Esvazie para extensões de raiz. | 
| startTime | Timestamp | Hora em que o período começou. | 
| endTime | Timestamp | Hora em que o período terminou. | 
| durationInNanos | Longo | Duração do intervalo em nanossegundos. | 
| status.code | Inteiro | Código de status do Span (0 = não definido, 1 = OK, 2 = erro). | 

**Atributos do GenAI**  
Os `gen_ai.*` atributos a seguir habilitam recursos específicos de IA na interface de usuário do Agent Traces:


| Atributo | Valor de exemplo | Description | 
| --- | --- | --- | 
| gen\$1ai.operation.name | chat | O tipo de operação do GenAI. Determina a categoria de extensão. | 
| gen\$1ai.system | openai | O sistema ou provedor de IA. | 
| gen\$1ai.request.model | gpt-4 | O modelo usado para a solicitação. | 
| gen\$1ai.usage.input\$1tokens | 150 | Número de tokens de entrada consumidos. | 
| gen\$1ai.usage.output\$1tokens | 85 | Número de tokens de saída gerados. | 
| gen\$1ai.response.finish\$1reasons | ["stop"] | Motivos pelos quais o modelo parou de gerar. | 

### Layout da página e barra de métricas
<a name="observability-ai-page-layout"></a>

A página Rastreamentos do agente exibe uma barra de métricas na parte superior que resume as principais estatísticas de todos os rastreamentos visíveis. As métricas incluem contagem total de rastreamentos, duração média, taxa de erro e uso de tokens. Esses valores são atualizados dinamicamente com base no filtro de tempo e na consulta.

### Aba Traços
<a name="observability-ai-traces-tab"></a>

A guia Traços lista todos os rastreamentos do agente raiz que correspondem à sua consulta atual e ao intervalo de tempo. Cada linha representa uma única invocação de agente.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/agent-traces/traces-table.png)


A tabela a seguir descreve as colunas na tabela de rastreamentos:


| Coluna | Description | 
| --- | --- | 
| ID de rastreamento | Identificador exclusivo para o rastreamento. Escolha o link para abrir o menu suspenso de detalhes do rastreamento. | 
| Nome do agente | Nome do agente que iniciou o rastreamento. | 
| Status | Status geral do rastreamento (OK ou Erro). | 
| Duração | Tempo total do primeiro intervalo até o último intervalo no rastreamento. | 
| Segmentos | Número total de extensões no traçado. | 
| Tokens de entrada | Total de tokens de entrada consumidos em todas as chamadas LLM no rastreamento. | 
| Tokens de saída | Total de tokens de saída gerados em todas as chamadas LLM no rastreamento. | 
| Horário de início | Registro de data e hora em que o rastreamento começou. | 

### Categorias de abrangência
<a name="observability-ai-span-categories"></a>

Os intervalos são categorizados com base no atributo`gen_ai.operation.name`. Cada categoria é exibida com uma cor e um ícone exclusivos na interface do usuário.


| Nome da operação | Categoria | Description | 
| --- | --- | --- | 
| invoke\$1agent, create\$1agent | Agente | Etapa de orquestração do agente. | 
| chat | LLM | Chamada de conclusão do bate-papo LLM. | 
| text\$1completion, generate\$1content | Conteúdo | Operação de geração de texto. | 
| execute\$1tool | Ferramenta | Invocação da ferramenta. | 
| embeddings | Incorporações | Geração de incorporação. | 
| retrieval | Recuperação | Operação de recuperação de dados. | 

### Aba de extensões
<a name="observability-ai-spans-tab"></a>

A guia Expansões exibe extensões individuais em todos os traços. Você pode filtrar e classificar períodos para encontrar operações específicas.

![\[alt text not found\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/agent-traces/spans-table.png)


### Menu de detalhes do rastreamento
<a name="observability-ai-trace-details"></a>

Quando você escolhe uma ID de rastreamento, um painel suspenso é aberto com duas áreas principais:
+ **Painel esquerdo** — Exibe a árvore de rastreamento, que mostra as relações hierárquicas entre pais e filhos entre as extensões. Também inclui um DAG de fluxo (gráfico acíclico direcionado) que visualiza o caminho de execução do agente.
+ **Painel direito** — contém duas guias. A guia **Detalhes** mostra atributos de extensão, atributos de recursos e metadados específicos do Genai. A guia **Cronograma** mostra um gráfico em cascata das durações dos períodos e suas relações temporais.

### Consultando traços
<a name="observability-ai-querying"></a>

O Agent Traces usa PPL (Piped Processing Language) para todas as buscas de dados. Você pode escrever consultas no painel de consultas na parte superior da página.

**Para listar traços de raiz**  
A consulta a seguir retorna os 100 rastreamentos mais recentes do agente raiz:

```
source = otel-v1-apm-span-*
| where parentSpanId = "" AND isnotnull(`attributes.gen_ai.operation.name`)
| sort - startTime
| head 100
```

**Para buscar todos os intervalos para um rastreamento**  
A consulta a seguir retorna a árvore de extensão completa de um rastreamento específico:

```
source = otel-v1-apm-span-*
| where traceId = "trace-id"
| head 1000
```

**Para calcular métricas agregadas**  
A consulta a seguir calcula a duração média e o uso total do token agrupados por modelo:

```
source = otel-v1-apm-span-*
| where isnotnull(`attributes.gen_ai.request.model`)
| stats avg(durationInNanos) as avg_duration,
        sum(`attributes.gen_ai.usage.input_tokens`) as total_input_tokens,
        sum(`attributes.gen_ai.usage.output_tokens`) as total_output_tokens
    by `attributes.gen_ai.request.model`
```