Traces de OpenTelemetry no New Relic

OpenTelemetry fornece um rico ecossistema de rastreamento, com uma API para registrar telemetria de trace um SDK para exportar dados de extensão e propagação de contexto para rastreamento através dos limites do aplicativo.

Esta página descreve como New Relic lida com os intervalos OpenTelemetry que recebe por meio do New Relic OTLP endpoint. Para enviar o rastreamento OpenTelemetry para New Relic, você precisará configurar sua origem trace para exportar dados para o coletor do New Relic OpenTelemetry por meio do endpoint OTLP. Veja as páginas seguintes:

Para requisitos de configuração endpoint , consulte New Relic OTLP endpoint.
Para obter instruções sobre como configurar serviços com OpenTelemetry, consulte MonitoramentoOpenTelemetry APM .

Mapeamento de intervalo OTLP

O New Relic mapeia extensões OTLP para o tipo de dados Span . A tabela abaixo descreve como os campos das definições de mensagens do protocolo de rastreamento são interpretados:

Campo proto OTLP	Campo New Relic `Span`
`ResourceSpans.Resource.attributes`	Cada valor principal é um atributo no `Span` [1]
`ScopeSpans.InstrumentationScope.name`	`otel.library.name`
`ScopeSpans.InstrumentationScope.version`	`otel.library.version`
`ScopeSpans.InstrumentationScope.attributes`	Cada valor principal é um atributo no `Span` [1]
`Span.trace_id`	`trace.id`
`Span.span_id`	`id`
`Span.trace_state`	`w3c.tracestate`
`Span.parent_span_id`	`parent.id`
`Span.name`	`name`
`Span.kind`	`span.kind`
`Span.start_time_unix_nano`	`timestamp`
`Span.end_time_unix_nano`	`duration.ms` (computar com `Span.start_time_unix_nano`)
`Span.attributes`	Cada valor principal é um atributo no `Span` [1]
`Span.dropped_attribute_count`	`otel.dropped_attributes_count`
`Span.events`	Cada evento é registrado como um `SpanEvent` com `span.id` / `trace.id` referindo-se ao intervalo de origem, contagem armazenada como `nr.spanEventCount`
`Span.events[*].time_unix_nano`	Armazenado como `timestamp` em `SpanEvent`
`Span.events[*].name`	Armazenado como `name` em `SpanEvent`
`Span.events[*].attributes`	Cada valor principal é armazenado como um atributo no `SpanEvent`
`Span.events[*].dropped_attributes_count`	Armazenado como `ote.dropped_Attributes_count` em `SpanEvent`
`Span.dropped_events_count`	`otel.dropped_events_count`
`Span.status.message`	`otel.status_description`
`Span.status.code`	`otel.status_code`

Notas de rodapé da tabela

[1] Em caso de conflito nos campos atributo de recurso, atributo de escopo, atributo de extensão e extensão de nível superior, a ordem de precedente (do maior para o menor) é os campos de nível superior Span.* > Span.attributes > ScopeSpans.InstrumentationScope.attributes > ResourceSpans.Resource.attributes.

Consulte os tipos de atributos OTLP para obter detalhes sobre os tipos de atributos suportados New Relic OTLP endpoint e os limites de atributos OTLP para obter detalhes sobre a validação realizada no atributo.

Links de extensão

O New Relic suporta links de span do OpenTelemetry, que permitem criar relações causais entre spans que não possuem uma conexão direta pai-filho. Os links de span são essenciais para a compreensão de rastreamentos distribuídos que são divididos em limites assíncronos, como filas de mensagens, fluxos de eventos e sistemas de processamento em lote.

Quando usar links span

Utilize links de extensão (span) nos seguintes cenários:

Message queue producers and consumersAo processar mensagens de filas como AWS SQS, RabbitMQ ou Kafka, vincule um span de consumo ao span de produção.
Fan-in patternsVincular vários rastreamentos de produtores a um único trace de consumidores que agrega suas saídas.
Batch processing: Vincula trechos de links que processam mensagens em lote de volta ao seu rastreamento de origem individual.
Long-running workflowsConecta trechos que atravessam etapas de fluxo de trabalho que excedem os limites normais de duração trace.

Implementando links de extensão

Para implementar links de extensão em sua instrumentação OpenTelemetry, você precisa:

Extrair o contexto do trace da mensagem ou evento recebido
Crie um link de span ao iniciar um novo span no consumidor.
Garanta que o contexto do trace seja propagado por toda a sua infraestrutura de mensagens.

Os exemplos a seguir mostram como implementar links de extensão em diferentes idiomas:

from opentelemetry import trace
from opentelemetry.trace import Link, SpanContext, TraceFlags
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

tracer = trace.get_tracer(__name__)
propagator = TraceContextTextMapPropagator()

# Producer: Publishing a message with trace context
def publish_message(queue, message_body):
    with tracer.start_as_current_span("publish_message") as span:
        # Prepare message with trace context headers
        carrier = {}
        propagator.inject(carrier)

        # Add carrier headers to your message metadata
        message = {
            'body': message_body,
            'headers': carrier
        }

        queue.publish(message)
        span.set_attribute("messaging.destination", queue.name)
        span.set_attribute("messaging.system", "custom_queue")

# Consumer: Processing a message with span link
def process_message(message):
    # Extract trace context from message headers
    carrier = message.get('headers', {})
    ctx = propagator.extract(carrier)

    # Get the span context from the extracted context
    span_context = trace.get_current_span(ctx).get_span_context()

    # Create a new span with a link to the producer span
    links = []
    if span_context.is_valid:
        links = [Link(span_context)]

    with tracer.start_as_current_span(
        "process_message",
        links=links
    ) as span:
        # Process the message
        result = handle_message(message['body'])

        span.set_attribute("messaging.system", "custom_queue")
        span.set_attribute("messaging.operation", "process")

        return result

Especificamente para o AWS SQS:

import boto3
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

sqs = boto3.client('sqs')
propagator = TraceContextTextMapPropagator()

# Publishing to SQS
def send_sqs_message(queue_url, message_body):
    with tracer.start_as_current_span("sqs_publish") as span:
        carrier = {}
        propagator.inject(carrier)

        # SQS message attributes for trace context
        message_attributes = {
            'traceparent': {
                'StringValue': carrier.get('traceparent', ''),
                'DataType': 'String'
            }
        }

        if 'tracestate' in carrier:
            message_attributes['tracestate'] = {
                'StringValue': carrier['tracestate'],
                'DataType': 'String'
            }

        sqs.send_message(
            QueueUrl=queue_url,
            MessageBody=message_body,
            MessageAttributes=message_attributes
        )

# Consuming from SQS
def process_sqs_message(message):
    # Extract trace context from SQS message attributes
    carrier = {}
    if 'MessageAttributes' in message:
        attrs = message['MessageAttributes']
        if 'traceparent' in attrs:
            carrier['traceparent'] = attrs['traceparent']['StringValue']
        if 'tracestate' in attrs:
            carrier['tracestate'] = attrs['tracestate']['StringValue']

    ctx = propagator.extract(carrier)
    span_context = trace.get_current_span(ctx).get_span_context()

    links = [Link(span_context)] if span_context.is_valid else []

    with tracer.start_as_current_span(
        "sqs_process",
        links=links
    ) as span:
        # Process message
        body = message['Body']
        return handle_message(body)

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanBuilder;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.propagation.TextMapGetter;
import io.opentelemetry.context.propagation.TextMapPropagator;
import io.opentelemetry.context.propagation.TextMapSetter;

public class MessageProcessor {
    private final Tracer tracer;
    private final TextMapPropagator propagator;

    // Producer: Publishing a message with trace context
    public void publishMessage(Queue queue, String messageBody) {
        Span span = tracer.spanBuilder("publish_message")
            .startSpan();

        try (var scope = span.makeCurrent()) {
            // Inject trace context into message headers
            Map<String, String> headers = new HashMap<>();
            propagator.inject(Context.current(), headers,
                (carrier, key, value) -> carrier.put(key, value));

            Message message = new Message(messageBody, headers);
            queue.publish(message);

            span.setAttribute("messaging.destination", queue.getName());
            span.setAttribute("messaging.system", "custom_queue");
        } finally {
            span.end();
        }
    }

    // Consumer: Processing a message with span link
    public void processMessage(Message message) {
        // Extract trace context from message headers
        Context extractedContext = propagator.extract(
            Context.current(),
            message.getHeaders(),
            (carrier, key) -> carrier.get(key)
        );

        // Get the span context from extracted context
        SpanContext producerSpanContext = Span.fromContext(extractedContext)
            .getSpanContext();

        // Create span with link to producer
        SpanBuilder spanBuilder = tracer.spanBuilder("process_message");

        if (producerSpanContext.isValid()) {
            spanBuilder.addLink(producerSpanContext);
        }

        Span span = spanBuilder.startSpan();

        try (var scope = span.makeCurrent()) {
            handleMessage(message.getBody());

            span.setAttribute("messaging.system", "custom_queue");
            span.setAttribute("messaging.operation", "process");
        } finally {
            span.end();
        }
    }

    // AWS SQS example
    public void processSQSMessage(
        software.amazon.awssdk.services.sqs.model.Message sqsMessage
    ) {
        Map<String, String> carrier = new HashMap<>();

        // Extract trace context from SQS message attributes
        sqsMessage.messageAttributes().forEach((key, value) -> {
            if (key.equals("traceparent") || key.equals("tracestate")) {
                carrier.put(key, value.stringValue());
            }
        });

        Context extractedContext = propagator.extract(
            Context.current(),
            carrier,
            (c, k) -> c.get(k)
        );

        SpanContext producerSpanContext = Span.fromContext(extractedContext)
            .getSpanContext();

        SpanBuilder spanBuilder = tracer.spanBuilder("sqs_process");

        if (producerSpanContext.isValid()) {
            spanBuilder.addLink(producerSpanContext);
        }

        Span span = spanBuilder.startSpan();

        try (var scope = span.makeCurrent()) {
            handleMessage(sqsMessage.body());
            span.setAttribute("messaging.system", "AmazonSQS");
        } finally {
            span.end();
        }
    }
}

const { trace, context, SpanKind } = require('@opentelemetry/api');
const { W3CTraceContextPropagator } = require('@opentelemetry/core');

const tracer = trace.getTracer('message-processor');
const propagator = new W3CTraceContextPropagator();

// Producer: Publishing a message with trace context
async function publishMessage(queue, messageBody) {
  const span = tracer.startSpan('publish_message', {
    kind: SpanKind.PRODUCER
  });

  return context.with(trace.setSpan(context.active(), span), async () => {
    try {
      // Inject trace context into message headers
      const carrier = {};
      propagator.inject(
        context.active(),
        carrier,
        {
          set: (carrier, key, value) => {
            carrier[key] = value;
          }
        }
      );

      const message = {
        body: messageBody,
        headers: carrier
      };

      await queue.publish(message);

      span.setAttribute('messaging.destination', queue.name);
      span.setAttribute('messaging.system', 'custom_queue');
    } finally {
      span.end();
    }
  });
}

// Consumer: Processing a message with span link
async function processMessage(message) {
  // Extract trace context from message headers
  const extractedContext = propagator.extract(
    context.active(),
    message.headers || {},
    {
      get: (carrier, key) => carrier[key]
    }
  );

  // Get the span context from extracted context
  const producerSpan = trace.getSpan(extractedContext);
  const producerSpanContext = producerSpan?.spanContext();

  // Create span with link
  const links = [];
  if (producerSpanContext && trace.isSpanContextValid(producerSpanContext)) {
    links.push({
      context: producerSpanContext
    });
  }

  const span = tracer.startSpan(
    'process_message',
    {
      kind: SpanKind.CONSUMER,
      links: links
    }
  );

  return context.with(trace.setSpan(context.active(), span), async () => {
    try {
      await handleMessage(message.body);

      span.setAttribute('messaging.system', 'custom_queue');
      span.setAttribute('messaging.operation', 'process');
    } finally {
      span.end();
    }
  });
}

// AWS SQS example using AWS SDK v3
const { SQSClient, SendMessageCommand, ReceiveMessageCommand } = require('@aws-sdk/client-sqs');

async function sendSQSMessage(queueUrl, messageBody) {
  const span = tracer.startSpan('sqs_publish');

  return context.with(trace.setSpan(context.active(), span), async () => {
    try {
      const carrier = {};
      propagator.inject(context.active(), carrier, {
        set: (c, k, v) => { c[k] = v; }
      });

      const messageAttributes = {
        traceparent: {
          StringValue: carrier.traceparent || '',
          DataType: 'String'
        }
      };

      if (carrier.tracestate) {
        messageAttributes.tracestate = {
          StringValue: carrier.tracestate,
          DataType: 'String'
        };
      }

      const client = new SQSClient({});
      await client.send(new SendMessageCommand({
        QueueUrl: queueUrl,
        MessageBody: messageBody,
        MessageAttributes: messageAttributes
      }));
    } finally {
      span.end();
    }
  });
}

async function processSQSMessage(message) {
  const carrier = {};

  if (message.MessageAttributes) {
    if (message.MessageAttributes.traceparent) {
      carrier.traceparent = message.MessageAttributes.traceparent.StringValue;
    }
    if (message.MessageAttributes.tracestate) {
      carrier.tracestate = message.MessageAttributes.tracestate.StringValue;
    }
  }

  const extractedContext = propagator.extract(context.active(), carrier, {
    get: (c, k) => c[k]
  });

  const producerSpanContext = trace.getSpan(extractedContext)?.spanContext();
  const links = producerSpanContext && trace.isSpanContextValid(producerSpanContext)
    ? [{ context: producerSpanContext }]
    : [];

  const span = tracer.startSpan('sqs_process', { links });

  return context.with(trace.setSpan(context.active(), span), async () => {
    try {
      await handleMessage(message.Body);
      span.setAttribute('messaging.system', 'AmazonSQS');
    } finally {
      span.end();
    }
  });
}

package main

import (
    "context"
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/trace"
)

var (
    tracer     = otel.Tracer("message-processor")
    propagator = propagation.TraceContext{}
)

// Producer: Publishing a message with trace context
func publishMessage(ctx context.Context, queue Queue, messageBody string) error {
    ctx, span := tracer.Start(ctx, "publish_message")
    defer span.End()

    // Inject trace context into message headers
    carrier := propagation.MapCarrier{}
    propagator.Inject(ctx, carrier)

    message := Message{
        Body:    messageBody,
        Headers: map[string]string(carrier),
    }

    err := queue.Publish(message)

    span.SetAttributes(
        attribute.String("messaging.destination", queue.Name()),
        attribute.String("messaging.system", "custom_queue"),
    )

    return err
}

// Consumer: Processing a message with span link
func processMessage(ctx context.Context, message Message) error {
    // Extract trace context from message headers
    carrier := propagation.MapCarrier(message.Headers)
    extractedCtx := propagator.Extract(ctx, carrier)

    // Get the span context from extracted context
    producerSpanContext := trace.SpanContextFromContext(extractedCtx)

    // Create span with link
    var links []trace.Link
    if producerSpanContext.IsValid() {
        links = []trace.Link{
            {
                SpanContext: producerSpanContext,
            },
        }
    }

    ctx, span := tracer.Start(
        ctx,
        "process_message",
        trace.WithLinks(links...),
    )
    defer span.End()

    err := handleMessage(message.Body)

    span.SetAttributes(
        attribute.String("messaging.system", "custom_queue"),
        attribute.String("messaging.operation", "process"),
    )

    return err
}

// AWS SQS example
func processSQSMessage(ctx context.Context, sqsMessage *sqs.Message) error {
    // Extract trace context from SQS message attributes
    carrier := propagation.MapCarrier{}

    if sqsMessage.MessageAttributes != nil {
        if tp, ok := sqsMessage.MessageAttributes["traceparent"]; ok {
            carrier["traceparent"] = *tp.StringValue
        }
        if ts, ok := sqsMessage.MessageAttributes["tracestate"]; ok {
            carrier["tracestate"] = *ts.StringValue
        }
    }

    extractedCtx := propagator.Extract(ctx, carrier)
    producerSpanContext := trace.SpanContextFromContext(extractedCtx)

    var links []trace.Link
    if producerSpanContext.IsValid() {
        links = []trace.Link{
            {SpanContext: producerSpanContext},
        }
    }

    ctx, span := tracer.Start(
        ctx,
        "sqs_process",
        trace.WithLinks(links...),
    )
    defer span.End()

    err := handleMessage(*sqsMessage.Body)

    span.SetAttributes(
        attribute.String("messaging.system", "AmazonSQS"),
    )

    return err
}

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Context.Propagation;

public class MessageProcessor
{
    private static readonly ActivitySource ActivitySource = new("MessageProcessor");
    private static readonly TextMapPropagator Propagator = Propagators.DefaultTextMapPropagator;

    // Producer: Publishing a message with trace context
    public async Task PublishMessage(IQueue queue, string messageBody)
    {
        using var activity = ActivitySource.StartActivity("publish_message", ActivityKind.Producer);

        // Inject trace context into message headers
        var carrier = new Dictionary<string, string>();
        Propagator.Inject(
            new PropagationContext(activity.Context, Baggage.Current),
            carrier,
            (c, key, value) => c[key] = value
        );

        var message = new Message
        {
            Body = messageBody,
            Headers = carrier
        };

        await queue.PublishAsync(message);

        activity?.SetTag("messaging.destination", queue.Name);
        activity?.SetTag("messaging.system", "custom_queue");
    }

    // Consumer: Processing a message with span link
    public async Task ProcessMessage(Message message)
    {
        // Extract trace context from message headers
        var propagationContext = Propagator.Extract(
            default,
            message.Headers ?? new Dictionary<string, string>(),
            (carrier, key) => carrier.TryGetValue(key, out var value) ? new[] { value } : Array.Empty<string>()
        );

        var producerContext = propagationContext.ActivityContext;

        // Create span with link
        var links = new List<ActivityLink>();
        if (producerContext != default)
        {
            links.Add(new ActivityLink(producerContext));
        }

        using var activity = ActivitySource.StartActivity(
            "process_message",
            ActivityKind.Consumer,
            parentContext: default,
            links: links
        );

        await HandleMessage(message.Body);

        activity?.SetTag("messaging.system", "custom_queue");
        activity?.SetTag("messaging.operation", "process");
    }

    // AWS SQS example
    public async Task ProcessSQSMessage(Amazon.SQS.Model.Message sqsMessage)
    {
        // Extract trace context from SQS message attributes
        var carrier = new Dictionary<string, string>();

        if (sqsMessage.MessageAttributes != null)
        {
            if (sqsMessage.MessageAttributes.TryGetValue("traceparent", out var tp))
            {
                carrier["traceparent"] = tp.StringValue;
            }
            if (sqsMessage.MessageAttributes.TryGetValue("tracestate", out var ts))
            {
                carrier["tracestate"] = ts.StringValue;
            }
        }

        var propagationContext = Propagator.Extract(
            default,
            carrier,
            (c, key) => c.TryGetValue(key, out var value) ? new[] { value } : Array.Empty<string>()
        );

        var links = new List<ActivityLink>();
        if (propagationContext.ActivityContext != default)
        {
            links.Add(new ActivityLink(propagationContext.ActivityContext));
        }

        using var activity = ActivitySource.StartActivity(
            "sqs_process",
            ActivityKind.Consumer,
            parentContext: default,
            links: links
        );

        await HandleMessage(sqsMessage.Body);

        activity?.SetTag("messaging.system", "AmazonSQS");
    }
}

práticas recomendadas para links de extensão

Ao implementar links de extensão, siga estas práticas recomendadas:

Always propagate trace context: Garantir que o contexto de rastreamento W3C (cabeçalhos traceparent e tracestate) esteja incluído nos cabeçalhos da mensagem ou.
Validate span contextSempre verifique se o contexto do span extraído é válido antes de criar um link span. Contextos inválidos não devem criar links.
Use appropriate span kindsDefina o tipo PRODUCER para os intervalos de publicação de mensagens e o tipo CONSUMER para os intervalos de processamento de mensagens.
Add messaging attributes: Inclua convenções semânticas para sistemas de mensagens (como messaging.system, messaging.destination, messaging.operation) para fornecer contexto.
Consider samplingAmbos os rastreamentos vinculados devem ser amostrados para aparecerem no New Relic. Ajustar estratégias de amostragem para fluxos de trabalho críticos que usam links de extensão.
Handle batch processing carefullyAo processar mensagens em lote, crie links de intervalo individuais para cada mensagem para manter a rastreabilidade.

Visualizando links de extensão no New Relic

Depois de implementar links de extensão em sua instrumentação, você poderá visualizá-los e navegar por eles na interface do usuário do New Relic:

Acesse a página de detalhestrace para obter um trace
Procure o selo de links de span na barra de filtros, que mostra o número de spans com links.
Selecione um elemento span com links para ver a guia Span links no painel de detalhes do elemento span.
Clique no traço vinculado para navegar entre os traços relacionados.

Para obter informações detalhadas sobre como usar links de extensão na interface do usuário, consulte Compreendendo os links de extensão.

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

Mapeamento de intervalo OTLP

Notas de rodapé da tabela

Links de extensão

Quando usar links span

Implementando links de extensão

Python

Java

Node.js

Go

.NET

práticas recomendadas para links de extensão

Visualizando links de extensão no New Relic

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

Traces de OpenTelemetry no New Relic

Mapeamento de intervalo OTLP .css-21sua1{background:none;border:none;width:0;padding:0;}

Notas de rodapé da tabela

Links de extensão

Quando usar links span

Implementando links de extensão

Java

Node.js

Go

.NET

práticas recomendadas para links de extensão

Visualizando links de extensão no New Relic

Mapeamento de intervalo OTLP