Envie os traces de GenAI para a New Relic com OpenTelemetry

Assim que o aplicativo começar a enviar traces de GenAI do OpenTelemetry (OTel) para a New Relic, a visualização do AI Monitoring mostra:

Cada chamada de LLM feita pelo serviço — prompt, conclusão, modelo, latência, contagens de token, motivo de conclusão.
Chamadas de ferramentas e etapas do agente como parte do trace completo da solicitação, para que você possa ver por que um modelo tomou uma decisão.
Erros, falhas de limite de taxa e chamadas lentas exibidas junto com o restante dos seus dados de APM.

Nenhum agente da New Relic é necessário. Se o aplicativo já emite traces do OpenTelemetry, a maior parte do caminho já foi percorrida.

Antes que você comece

Você precisará:

Uma chave de licença de ingestão da New Relic.
Um aplicativo que chama um LLM. Exemplos em Python para OpenAI, Anthropic, LangChain e AWS Bedrock são mostrados abaixo. Outras linguagens com instrumentação GenAI do OpenTelemetry funcionam da mesma forma.
Saída de rede do aplicativo para o endpoint OTLP da New Relic para a região na porta 443. Para obter a lista completa de endpoints regionais (EUA, UE e JP), portas suportadas e configurações de compactação, consultar Enviar Dados para a New Relic Usando o OpenTelemetry Protocol (OTLP).

Importante

A instrumentação da GenAI do OTel pode capturar os prompts e as conclusões exatos que os usuários enviam e recebem. Isso pode incluir PII, credenciais ou dados regulamentados. A captura de conteúdo está desativada por padrão. Antes de ativá-la, revise as políticas de tratamento de dados da organização e consulte Controlar quais prompts e conclusões são enviados.

Aponte seu exportador do OpenTelemetry para o New Relic

Defina essas variáveis de ambiente no processo que executa seu aplicativo:

bash

$# Replace with your region's OTLP endpoint — see the prerequisites above for the full list
$export OTEL_EXPORTER_OTLP_ENDPOINT="<<YOUR_OTLP_ENDPOINT>>"
$export OTEL_EXPORTER_OTLP_HEADERS="api-key=$NEW_RELIC_LICENSE_KEY"
$
$# Name that will identify this service in New Relic
$export OTEL_SERVICE_NAME="my-genai-service"

Adicionar o pacote de instrumentação correto

Escolha a seção que corresponde ao que seu aplicativo usa. Você pode combinar mais de um — por exemplo, um aplicativo LangChain que chama o Bedrock instalaria ambos.

Dica

Os nomes e as versões exatas dos pacotes evoluem rapidamente no ecossistema GenAI do OpenTelemetry. Sempre verificar o registro de contribuição do OpenTelemetry Python e a documentação do New Relic AI Monitoring para o pacote que a equipe suporta atualmente.

Instale a instrumentação de GenAI da OpenAI oficial do projeto OpenTelemetry e, em seguida, execute seu aplicativo com opentelemetry-instrument ou chame o instrumentador explicitamente:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
OpenAIInstrumentor().instrument()

from openai import OpenAI
OpenAI().chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}],
)

Instale uma instrumentação Anthropic do OpenTelemetry (disponível no registro contrib do OpenTelemetry e em distribuições da comunidade, como o OpenLLMetry). Em seguida:

from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
AnthropicInstrumentor().instrument()

import anthropic
anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)

A instrumentação do LangChain abrange a cadeia, quaisquer chamadas de ferramenta e o cliente do modelo subjacente em um único pacote. Instale a instrumentação do LangChain da comunidade de sua escolha e ative-a na inicialização:

from opentelemetry.instrumentation.langchain import LangchainInstrumentor
LangchainInstrumentor().instrument()

Sua cadeia ChatOpenAI, ChatAnthropic ou semelhante existente receberá o trace automaticamente. As etapas da ferramenta e do agente aparecem como span filho sob a invocação da cadeia pai.

O tráfego do Bedrock passa pelo AWS SDK. Instale a instrumentação do OpenTelemetry do AWS SDK (botocore) e ative-a:

from opentelemetry.instrumentation.botocore import BotocoreInstrumentor
BotocoreInstrumentor().instrument()

import boto3, json
boto3.client("bedrock-runtime", region_name="us-east-1").invoke_model(
    modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 256,
        "messages": [{"role": "user", "content": "Hello"}],
    }),
)

Verifique se a sua versão instalada emite atributos do GenAI (gen_ai.system, gen_ai.request.model e uso de token) para chamadas do Bedrock — o suporte foi implementado de forma incremental entre as versões.

Verifique se seus dados estão chegando

Reinicie seu aplicativo para que as novas variáveis de ambiente e a instrumentação entrem em vigor.
Acione uma pequena quantidade de tráfego real — um punhado de conclusões de chat é suficiente.

No New Relic, abra Query Your Data e execute:

SELECT count(*) FROM Span
WHERE gen_ai.system IS NOT NULL OR gen_ai.provider.name IS NOT NULL
SINCE 30 minutes ago
FACET service.name, gen_ai.operation.name

Dentro de alguns minutos (2–5 min), será possível ver linhas facetadas pelo nome do serviço e operação (ex.: chat, completion, embeddings).
Acesse APM & Services > AI Monitoring e selecione o serviço para ver a visualização AI Traces ser preenchida.

Controle quais prompts e conclusões são enviados

Por padrão, a maioria das instrumentações de GenAI do OpenTelemetry não captura o texto de prompts ou conclusões. Os spans incluirão o modelo, as contagens de token, a latência e o status, mas não os corpos das mensagens.

Para tornar o conteúdo da mensagem visível no AI Monitoring, opte explicitamente. O nome do sinalizador depende do pacote de instrumentação instalado — verifique a documentação desse pacote específico. Exemplos comuns incluem:

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true para instrumentação mantida pelo OpenTelemetry.
TRACELOOP_TRACE_CONTENT=true para instrumentação da comunidade (família OpenLLMetry).

Antes de ativar a captura de conteúdo em produção:

Revisar os dados que os prompts contêm. Se os usuários enviarem PII, credenciais ou dados regulamentados, recomenda-se o uso de filtros de descarte ou ofuscação no nível do atributo para remover ou aplicar hash a campos específicos antes que sejam enviados para a New Relic. Consultar a Documentação de Tratamento de Dados da New Relic.
Verifique os requisitos de retenção e conformidade da organização (GDPR, HIPAA, PCI, etc.).

Se você precisar apenas de visibilidade de latência, token e erros — não de corpos de mensagens —, deixe a captura de conteúdo desativada.

Solucionar problemas

O que você vê	O que tentar
A consulta na etapa 3 retorna zero linhas	Confirme se o seu endpoint OTLP corresponde à região da sua conta e se o cabeçalho `api-key` contém uma chave de licença de ingestão válida (não uma chave de usuário).
Os spans chegam, mas a visualização do AI Monitoring está vazia para o serviço	Os spans podem não receber a tag com o atributo GenAI esperado. Atualize o pacote de instrumentação ou entre em contato com o suporte da New Relic com um span de amostra.
O prompt longo é cortado	Aumente `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` e `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` no lado do aplicativo.
As contagens de token estão ausentes	O provedor de LLM as retornou, mas sua versão de instrumentação ainda não as registra. Atualize o pacote de instrumentação.
O AI Monitoring mostra traces, mas os prompts/conclusões estão em branco	A captura de conteúdo está desativada. Consultar Controlar Quais Prompts e Conclusões São Enviados.
Espera-se que o AI Monitoring esteja disponível, mas a visualização não aparece	Entrar em contato com a equipe de contas da New Relic para confirmar se o AI Monitoring está ativado na conta.

Obter ajuda

Caso haja dificuldades após seguir as etapas acima:

Abra um caso de suporte do New Relic e inclua uma carga de span de amostra e o nome do seu serviço.
Entre em contato com a equipe da sua conta da New Relic para tirar dúvidas sobre a configuração no nível da conta.
Para dúvidas gerais sobre a GenAI do OpenTelemetry, as convenções semânticas da GenAI do OpenTelemetry são a referência oficial.

Esta tradução de máquina é fornecida para sua comodidade.