Suporte à API OpenTelemetry nos agentes New Relic

Pré-requisitos

Adicione as dependências necessárias do OpenTelemetry à sua aplicação:

implementation(platform("io.opentelemetry:opentelemetry-bom:1.44.1"))
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
implementation("io.opentelemetry:opentelemetry-exporter-otlp")

Habilitar suporte à API OpenTelemetry

1. Habilite a autoconfiguração do SDK do OpenTelemetry

Use um dos seguintes métodos:

Propriedade do sistema:

$
-Dotel.java.global-autoconfigure.enabled=true

Variável de ambiente:

$
export OTEL_JAVA_GLOBAL_AUTOCONFIGURE_ENABLED=true

2. Ativar o suporte ao New Relic OpenTelemetry

Propriedade do sistema:

$
-Dnewrelic.config.opentelemetry.enabled=true

Variável de ambiente:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

Configuração YAML (newrelic.yml):

opentelemetry:
  enabled: true

Tipos de instrumentação suportados

Instrumentação manual

A instrumentação personalizada usando as APIs de rastreamento, métricas ou logs do OpenTelemetry será capturada automaticamente pelo agente.

Biblioteca e instrumentação nativa

As instrumentações de biblioteca independentes do OpenTelemetry e a instrumentação nativa incorporada diretamente nas bibliotecas funcionarão com o agente New Relic. No entanto, a autoinstrumentação baseada em bytecode do OpenTelemetry não será detectada pelo agente New Relic.

Habilitar suporte à API OpenTelemetry

Habilite o suporte à API do OpenTelemetry no seu arquivo de configuração newrelic.js:

exports.config = {
  // ... other config
  opentelemetry: {
    enabled: true,
    traces: {
      enabled: true
    }
  }
  // ... other config
}

APIs do OpenTelemetry suportadas

Quando o suporte ao OpenTelemetry está ativado, o agente Node.js suporta totalmente:

API de Traces

Crie spans personalizados e adicione atributos usando a API de Rastreamento do OpenTelemetry. Veja o exemplo de rastreamento do OpenTelemetry para Node.js.

APImétrica

A API de Métricas é o recurso mais útil para clientes Node.js. Isso expande a capacidade de coleta de métricas para incluir métricas dimensionais, um recurso frequentemente solicitado.

Registre métricas personalizadas usando a API de Métricas do OpenTelemetry. Veja o exemplo de métricas do OpenTelemetry Node.js.

API de Logs

A API de Logs do OpenTelemetry para JavaScript ainda está em desenvolvimento, mas o agente Node.js oferece suporte a ela. Você pode usar a API para emitir logs que serão enviados para o New Relic.

Veja o exemplo de logs do OpenTelemetry Node.js.

Tipos de instrumentação suportados

Instrumentação manual (recomendada)

Clientes que instrumentam suas aplicações com a API do OpenTelemetry verão que o agente processa e envia esses dados corretamente.

Instrumentação nativa e de biblioteca (limitada)

A lista de instrumentações do OpenTelemetry tem uma sobreposição significativa com os módulos suportados pelo agente Node.js. Instrumentações que ainda não são cobertas pelo agente New Relic podem:

• Conflito com componentes internos do agente
• Não ter demanda suficiente do cliente

Limitações conhecidas

• Sem instrumentações automáticas: O agente não habilita automaticamente as instrumentações do OpenTelemetry. Os clientes devem instrumentar manualmente seu código usando as APIs do OpenTelemetry.

Habilitar suporte à API OpenTelemetry

Habilite o suporte à API do OpenTelemetry usando variáveis de ambiente ou o arquivo de configuração XML newrelic.config.

Usando variáveis de ambiente:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

Usando newrelic.config:

<configuration>
  <openTelemetry enabled="true" />
</configuration>

Instrumentações nativas suportadas

Ao ativar o suporte à API do OpenTelemetry, o agente .NET pode capturar telemetria de bibliotecas instrumentadas com OpenTelemetry.

Instrumentações de traces

O agente suporta bibliotecas com instrumentação nativa de tracing do OpenTelemetry. A instrumentação personalizada escrita usando a API de rastreamento do OpenTelemetry também é suportada.

Instrumentações de métricas

Quando as métricas estão habilitadas, o agente suporta instrumentações de métricas do OpenTelemetry de bibliotecas e frameworks. A instrumentação personalizada escrita usando a API de métricas do OpenTelemetry também é suportada.

Instrumentações de logs

O agente .NET já instrumenta a biblioteca de logging que se tornou a API OpenTelemetry para dados de log. Não são necessárias alterações para logs ao habilitar o suporte à API do OpenTelemetry. Para compatibilidade com versões anteriores, a instrumentação de log continua funcionando como antes.

Habilitar suporte à API OpenTelemetry

Habilite o suporte à API do OpenTelemetry no seu arquivo de configuração newrelic.ini ou usando variáveis de ambiente:

Usando newrelic.ini:

[newrelic]
opentelemetry.enabled = true

Usando variável de ambiente:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

Como funciona

Quando o suporte ao OpenTelemetry estiver habilitado e o agente detectar que o opentelemetry-api está instalado:

1. Instrumentação nativa: Para bibliotecas com instrumentação nativa do OpenTelemetry integrada, o agente desativa automaticamente os hooks da New Relic e utiliza a instrumentação nativa do OpenTelemetry.

2. Instrumentação de biblioteca: Se uma biblioteca de instrumentação do OpenTelemetry for detectada, o agente usa automaticamente a instrumentação do OpenTelemetry em vez dos hooks de instrumentação da New Relic.

Para a lista atual de instrumentações Python disponíveis, consulte a lista oficial de instrumentação Python do OpenTelemetry.

Instrumentação manual

Qualquer instrumentação personalizada escrita usando a API de rastreamento do OpenTelemetry será capturada pelo agente.

Exemplo:

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("my-custom-span") as span:
    span.set_attribute("custom.attribute", "value")
    # Your code here

Recurso suportado

API de Traces

✅ Totalmente suportado: Crie spans personalizados e adicione atributos usando a API de Tracing do OpenTelemetry

APImétrica

❌ Ainda não suportado: A OpenTelemetry Metrics API não está habilitada no agente Python

API de Logs

✅ Já funciona: O agente já suporta o módulo logging. Não há API do OpenTelemetry para logging em Python (existe apenas um SDK). O que o OpenTelemetry configura para logging é se ele está habilitado e para quais endpoints enviar dados.

Como funciona

Quando o suporte ao OpenTelemetry estiver habilitado:

1. O Agente pesquisa o sistema para determinar se as bibliotecas de instrumentação OpenTelemetry estão instaladas
2. Alternância automática: Se encontrada, o agente usa a instrumentação da biblioteca OpenTelemetry em vez dos hooks da New Relic
3. Integração perfeita: os spans do OpenTelemetry são integrados aos traces do New Relic

Limitações conhecidas

• Métricas não suportadas: A API de métricas do OpenTelemetry ainda não está habilitada
• Algumas bibliotecas da AWS e gRPC excluídas: Continuarão usando a instrumentação da New Relic
• Bibliotecas de IA desativadas: A instrumentação nativa do OpenTelemetry para bibliotecas de IA está desativada por enquanto
• Configurações de inclusão/exclusão: Opções de ajuste fino estão planejadas para versões futuras, mas apenas ativar/desativar está funcional no momento

Habilitar suporte à API OpenTelemetry

Para habilitar o suporte à API do OpenTelemetry no agente Ruby, adicione o seguinte ao seu arquivo de configuração newrelic.yml:

opentelemetry:
  enabled: true

Ou defina a variável de ambiente:

$
NEW_RELIC_OPENTELEMETRY_ENABLED=true

Instrumentação manual

Qualquer instrumentação personalizada escrita usando a API de rastreamento do OpenTelemetry será capturada pelo agente.

Exemplo:

require 'opentelemetry'

APP_TRACER = OpenTelemetry.tracer_provider.tracer('my-app', '1.0.0')

APP_TRACER.in_span("my-custom-span") do |span|
  span.set_attribute("test.attribute", "value")
  # Your code here
end

Recurso suportado

API de Traces

✅ Suportado: Criar spans personalizados e adicionar atributos usando a API de Tracing do OpenTelemetry

APImétrica

❌ Não suportado: API de Métricas do OpenTelemetry

API de Logs

❌ Não suportado: OpenTelemetry Logs API

Links de Span

❌ Não suportado: Span Links

Eventos em Spans

❌ Não suportado: Eventos em Spans

Como funciona

Quando o suporte ao OpenTelemetry está habilitado, o agente Ruby da New Relic:

1. Escuta chamadas feitas para as APIs de rastreamento do OpenTelemetry
2. Traduz essas chamadas em modelos de dados do New Relic
3. Incorpora spans do OpenTelemetry aos traces do New Relic

Limitações conhecidas

• Suporte limitado à API: Apenas a API de Traces é suportada nesta versão
• Métricas e Logs: Não disponível
• Links de Span e Eventos: Não suportado atualmente

Verifique a configuração do seu agente para confirmar se o suporte ao OpenTelemetry está ativado:

• Revise as variáveis de ambiente ou os arquivos de configuração
• Verifique os logs do agente para confirmar se o suporte ao OpenTelemetry está ativo
• Certifique-se de ter reiniciado sua aplicação após alterar a configuração

Confirme se você está executando a versão mínima necessária do agente que suporta as APIs do OpenTelemetry. Consulte a tabela de linguagens suportadas acima.