OpenTelemetry for AEM opentelemetry-apm

A Adobe está substituindo a integração do Application Performance Monitoring (APM) incorporada ao AEM as a Cloud Service pela OpenTelemetry, uma abordagem aberta padrão do setor para observabilidade suportada por todas as principais plataformas de monitoramento.

Atualmente, o AEM as a Cloud Service inclui uma integração de APM integrada, gerenciada totalmente pela Adobe. À medida que essa integração for substituída, você precisará trazer seu próprio ponto de extremidade APM — uma plataforma de fornecedor que aceite dados OpenTelemetry ou um back-end autohospedado (local) compatível com OpenTelemetry.

Benefícios dessa alteração benefits

Visão geral overview

O AEM as a Cloud Service pode emitir a telemetria de seu aplicativo usando OpenTelemetry, uma abordagem aberta padrão do setor para observabilidade, e encaminhá-la para o provedor de APM de sua escolha. Isso permite monitorar o aplicativo AEM junto com o restante dos sistemas nas ferramentas que suas equipes já usam.

Motivos comuns para usar essa integração incluem investigar solicitações lentas ou com falha, rastrear a integridade da JVM e o uso de recursos ao longo do tempo, criar painéis e alertas para seus níveis do AEM e correlacionar o comportamento do AEM com o restante dos serviços durante um incidente, tudo sem sair das ferramentas de monitoramento que suas equipes já usam.

A telemetria a seguir está no escopo:

O Encaminhamento de Log continua sendo suportado por meio de seu mecanismo separado existente, e não é afetado por essa integração.

Para saber como funciona, incluindo como a telemetria flui do AEM para a sua plataforma APM, o que você controla e como escolher uma plataforma, consulte o tutorial Observabilidade via OpenTelemetry.

Versões suportadas do OpenTelemetry supported-versions

O agente OpenTelemetry é executado como parte do tempo de execução do Cloud Service. A Adobe fornece e mantém a atualização, de modo que você mesmo não precisa instalá-la, gerenciá-la ou atualizá-la. A versão de patch específica pode mudar à medida que o Adobe atualiza o agente.

Variantes de OpenTelemetry compatíveis supported-variants

Seu aplicativo AEM pode ser instrumentado com qualquer uma das seguintes variantes do agente OpenTelemetry (distribuições), todas com base na versão acima. Consulte a documentação de cada projeto para obter detalhes:

A variante upstream padrão funciona com qualquer fornecedor de APM. As variantes do Grafana e do Splunk adicionam instrumentação específica do fornecedor e padrões para essas plataformas. O Adobe instala a variante de agente selecionada no contêiner do AEM na implantação. Durante a Disponibilidade Limitada, a variante upstream é usada por padrão. Para usar a variante do Grafana ou do Splunk, solicite-a ao solicitar acesso. O arquivo config/otel.yaml configura para onde a telemetria vai; não há nenhum campo para selecionar a variante do agente.

Fornecedores de APM apm-vendors

Você pode enviar sua telemetria para qualquer fornecedor do Application Performance Monitoring que aceite dados OpenTelemetry por OTLP/HTTPS. Isso é independente da variante OpenTelemetry escolhida. Os fornecedores com suporte a OTLP/HTTPS incluem:

Esta lista não é exaustiva — qualquer back-end que exponha um endpoint OTLP/HTTPS pode ser usado.

Ambientes compatíveis supported-environments

Você pode habilitar essa integração nos ambientes de produção, estágio e desenvolvimento do Cloud Manager. Cada ambiente é habilitado individualmente — consulte Etapa 1. Os ambientes de desenvolvimento rápido (RDE) não são compatíveis.

Integrações APM existentes existing-apm

OpenTelemetry não pode ser executado com outro agente APM no mesmo ambiente:

Conectividade de rede network-connectivity

O terminal do seu provedor de APM deve estar acessível no seu ambiente AEM as a Cloud Service por HTTPS.

Se o seu ponto de extremidade APM for privado ou se você precisar que o tráfego externo saia de um endereço IP estável e conhecido, essa integração oferecerá suporte ao Sistema de Rede Avançado com saída dedicada. Consulte Rede Avançada para saber como habilitá-la.

Quais dados são enviados what-data-is-sent

Somente os rastreamentos, as métricas e os logs (se habilitados) gerados pelo seu aplicativo AEM são enviados para o seu provedor de APM. Os exemplos a seguir ilustram o tipo de dados que você pode esperar.

Rastreamentos — abrange as solicitações manipuladas pelo seu aplicativo, incluindo:

O agendador interno de alto volume e a atividade de investigação de integridade (por exemplo, tarefas Quartz) são filtrados para que os rastreamentos permaneçam focados nas solicitações de aplicativos.

Métricas — as métricas de tempo de execução JVM e do servidor HTTP, que usam nomes de métricas OpenTelemetry padrão, e as métricas do AEM sob o prefixo aem. (que estão sendo implantadas; elas são exibidas automaticamente, sem alteração na configuração), incluindo:

Logs — as entradas de log do aplicativo AEM no nível WARN e superior, enviadas usando o sinal de logs de OpenTelemetry, quando habilitadas. A capacidade de ajustar esse nível de log está em desenvolvimento. As entradas de log têm os mesmos atributos de recurso que rastreamentos e métricas (service.name, deployment.environment) e os identificadores de rastreamento e span da solicitação que as produziu, para que possam ser correlacionadas com rastreamentos.

Os logs enviados dessa maneira são independentes do Encaminhamento de Logs — consulte Visão geral para saber por que habilitar ambos para o mesmo destino causa duplicatas.

Como a telemetria é identificada — cada rastreamento e métrica carrega atributos de recurso que identificam sua origem, incluindo:

As informações sobre o tempo de execução do Cloud Service e a plataforma que hospeda seu aplicativo — como nomes de host internos, endereços, identificadores de container e detalhes do sistema operacional ou do processo — são removidas antes que os dados saiam do ambiente.

Configurar a integração set-up

Para obter uma apresentação guiada que usa o projeto de amostra WKND, desde o armazenamento da credencial no Cloud Manager até a verificação de telemetria na plataforma de observabilidade, consulte o tutorial Configurar OpenTelemetry para obter insights sobre aplicativos do AEM.

Etapa 1: solicitar acesso request-access

Envie um email para aemcs-apm-beta@adobe.com com a ID do programa Cloud Manager e as IDs de ambiente que deseja habilitar. Se você quiser usar a variante do agente Grafana ou Splunk em vez do padrão, diga isso no seu email (consulte Variantes de OpenTelemetry compatíveis).

O Adobe habilita o OpenTelemetry para esses ambientes logo após responder à sua solicitação. Se um ambiente usa atualmente a integração APM integrada do Adobe, essa integração interrompe o envio de dados assim que OpenTelemetry é habilitada — consulte Integrações APM existentes.

Etapa 2: adicionar seu arquivo de configuração add-configuration

Adicione um arquivo config/otel.yaml ao repositório do Pipeline de configuração do Cloud Manager. No mínimo, especifique:

Consulte Exemplo de configuração abaixo para obter o formato de arquivo exato, incluindo exemplos para New Relic, Dynatrace, Grafana Cloud, Splunk, Datadog, Dash0 e pontos de extremidade genéricos ou auto-hospedados.

Etapa 3: configurar sua credencial de autenticação configure-credential

Forneça a credencial que seu provedor de APM requer declarando uma variável de ambiente secreta chamada OTEL_CUSTOMER_AUTH no Cloud Manager. Defina o Serviço Aplicado como Todos para que a credencial esteja disponível para os níveis de criação, publicação e visualização.

Para adicionar ou atualizar variáveis de ambiente, você deve ser membro da função de Gerente de Implantação. Para obter o procedimento completo, consulte Variáveis de ambiente no Cloud Manager.

Defina o valor de acordo com o método de autenticação do provedor:

Configurações específicas do provedor provider-specific

A tabela a seguir resume o endpoint e a autenticação de alguns provedores comuns. Sempre confirme os valores atuais na documentação do seu provedor. Para provedores que usam um cabeçalho personalizado (por exemplo, New Relic e Datadog), defina OTEL_CUSTOMER_AUTH somente como o valor bruto da chave e defina authHeaderName no arquivo de configuração com o nome de cabeçalho correto (consulte Exemplo de configuração).

Exemplo de configuração example-configuration

Adicione um arquivo como um dos seguintes exemplos a config/otel.yaml no repositório do Pipeline de configuração, com base no seu provedor de Configurações específicas do provedor.

New Relic:

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "newrelic"
  endpoint: "https://otlp.nr-data.net"   # https://otlp.eu01.nr-data.net for the EU region
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"
  metrics: true   # optional
  logs: true      # optional — see Overview for the Log Forwarding duplicate-message warning

Dynatrace:

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "dynatrace"
  endpoint: "https://{your-environment-id}.live.dynatrace.com/api/v2/otlp"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"   # the secret's value must be "Api-Token <token>"
  metrics: true
  logs: true

Datadog:

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "generic"
  endpoint: "https://otlp.<your-datadog-site>"   # for example, https://otlp.datadoghq.com
  authHeaderName: "dd-api-key"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"   # the secret's value is the raw API key, no prefix
  metrics: true
  logs: true

Traço0:

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "generic"
  endpoint: "https://ingress.<region>.aws.dash0.com:4318"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"   # the secret's value must be "Bearer <token>"
  metrics: true
  logs: true

Grafana Cloud:

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "grafana"
  endpoint: "https://otlp-gateway-<zone>.grafana.net/otlp"   # for example, https://otlp-gateway-prod-us-east-0.grafana.net/otlp
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"   # the secret's value must be "Basic <base64(instanceID:token)>"
  metrics: true
  logs: true

Splunk (por meio de uma Distribuição Splunk do Coletor OpenTelemetry em execução como gateway):

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "splunk"
  endpoint: "https://<your-splunk-otel-collector>:4318"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"   # the credential your gateway accepts, for example "Bearer <token>"
  metrics: true
  logs: true

Ponto de extremidade genérico ou auto-hospedado (por exemplo, um coletor OpenTelemetry local):

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "generic"
  endpoint: "https://<your-otlp-endpoint>"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"   # for example, "Basic <base64(user:pass)>"
  metrics: true
  logs: true

Rede Avançada (saída dedicada) — para um ponto de extremidade privado ou um que exija o tráfego de saída de um endereço IP estável e conhecido (consulte Conectividade de rede):

kind: "Otel"
version: "1"
metadata:
  envTypes:
    - "stage"
    - "prod"
data:
  enabled: true
  type: "generic"
  endpoint: "https://<your-private-otlp-endpoint>"
  authHeaderValue: "${{secrets.OTEL_CUSTOMER_AUTH}}"
  metrics: true
  logs: true
  advancedNetworking: true   # routes this endpoint's egress through Advanced Networking instead of direct internet egress

Etapa 4: implantar deploy

Depois que a Adobe confirmar que o OpenTelemetry está habilitado para o seu ambiente (consulte Etapa 1), execute o Pipeline de Configuração para implantar config/otel.yaml. O pipeline valida sua configuração e verifica seu endpoint e credencial antes de aplicar a configuração, portanto, a maioria dos erros é relatada diretamente no log de pipeline.

Depois que o pipeline for concluído, os rastreamentos, as métricas e os logs (se ativados) do aplicativo do AEM começarão a aparecer no provedor de APM. Use a Etapa 5 para confirmar.

Etapa 5: verificar a integração verify

Como a telemetria é enviada para seu próprio provedor de APM, você confirma a integração com as ferramentas de seu provedor; a Adobe não exibe esses dados de volta para você.

Depois que o pipeline for concluído, aguarde alguns minutos para a chegada dos dados e verifique o provedor de APM para obter o seguinte:

Se esses dados forem exibidos, a integração está funcionando.

Resolução de problemas troubleshooting

Se a telemetria não aparecer no seu provedor de APM, verifique o seguinte:

Se a telemetria ainda não aparecer após essas verificações, contate aemcs-apm-beta@adobe.com com os detalhes do programa e do ambiente.

Perguntas frequentes faq

Por que esta alteração está acontecendo?

Os clientes do AEM as a Cloud Service solicitaram métricas e dados operacionais adicionais, bem como rastreamentos, extensões e logs no contexto. OpenTelemetry é um padrão do setor que aceita todos esses recursos e os coloca em um formato amplamente compatível (OTLP).

Preciso solicitar acesso?

Sim. Durante a Disponibilidade Limitada, envie um email para aemcs-apm-beta@adobe.com com suas IDs de programa e ambiente. O Adobe habilita o OpenTelemetry para esses ambientes logo após responder à sua solicitação. Isso ainda não está disponível para ambientes com escopo HIPAA.

O que acontece com o New Relic se eu habilitar OpenTelemetry?

Uma vez que o Adobe habilite o OpenTelemetry para um ambiente a sua solicitação, os dados não serão mais enviados para o New Relic a partir desse ambiente. Os dois não podem ser executados ao mesmo tempo.

Se eu migrar do New Relic para o OpenTelemetry, posso voltar?

Sim. O email aemcs-apm-beta@adobe.com e o Adobe desabilitam o OpenTelemetry para seus ambientes. Em seguida, defina enabled: false no arquivo config/otel.yaml (ou remova o arquivo), execute o Pipeline de configuração e execute um pipeline de Empilhamento completo para concluir a restauração do New Relic. Isso é possível até o final de novembro de 2026.

Posso usar OpenTelemetry se meu ambiente executar o Dynatrace OneAgent?

Não no mesmo ambiente — o Dynatrace OneAgent tem prioridade. Você pode remover o OneAgent e usar OpenTelemetry, incluindo com o Dynatrace como seu provedor de APM. Consulte Integrações APM existentes.

O que acontece após novembro de 2026?

A Adobe mudará de sua solução integrada de APM para OpenTelemetry como sua solução de observabilidade permanente.

Artigos relacionados related-articles