Trazas de OpenTelemetry en New Relic

OpenTelemetry proporciona un rico ecosistema de rastreo, con una API para registrar traza telemetría, un SDK para exportar datos de tramo y distribución del contexto para rastrear a través de los límites de las aplicaciones.

Esta página describe cómo New Relic maneja los intervalos de OpenTelemetry que recibe a través del extremo OTLP New Relic . Para enviar OpenTelemetry trazas a New Relic, deberá configurar su fuente de trazas para exportar datos al New Relic OpenTelemetry recolector a través del extremo OTLP. Vea las siguientes páginas:

Para conocer los requisitos de configuración del extremo, consulte Extremo OTLP New Relic .
Para obtener instrucciones sobre cómo configurar servicios con OpenTelemetry, consulte MonitoreoOpenTelemetry APM .

Mapeo de tramo OTLP

New Relic asigna intervalos OTLP al tipo de datos Span . La siguiente tabla describe cómo se interpretan los campos de las definiciones de mensajes del protocolo traza :

Campo proto OTLP	Campo New Relic `Span`
`ResourceSpans.Resource.attributes`	Cada valor principal es un atributo en el `Span` [1]
`ScopeSpans.InstrumentationScope.name`	`otel.library.name`
`ScopeSpans.InstrumentationScope.version`	`otel.library.version`
`ScopeSpans.InstrumentationScope.attributes`	Cada valor principal es un atributo en el `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` (calcular con `Span.start_time_unix_nano`)
`Span.attributes`	Cada valor principal es un atributo en el `Span` [1]
`Span.dropped_attribute_count`	`otel.dropped_attributes_count`
`Span.events`	Cada evento se registra como `SpanEvent` con `span.id` / `trace.id` haciendo referencia al intervalo de origen, el recuento se almacena como `nr.spanEventCount`
`Span.events[*].time_unix_nano`	Almacenado como `timestamp` el `SpanEvent`
`Span.events[*].name`	Almacenado como `name` el `SpanEvent`
`Span.events[*].attributes`	Cada valor principal se almacena como un atributo en `SpanEvent`
`Span.events[*].dropped_attributes_count`	Almacenado como `ote.dropped_Attributes_count` el `SpanEvent`
`Span.dropped_events_count`	`otel.dropped_events_count`
`Span.status.message`	`otel.status_description`
`Span.status.code`	`otel.status_code`

Notas a pie de tabla

[1] En caso de conflicto en el atributo de recurso, el atributo de alcance, el atributo span y los campos span de nivel superior, el orden del precedente (de mayor a menor) es los campos de nivel superior Span.* > Span.attributes > ScopeSpans.InstrumentationScope.attributes > ResourceSpans.Resource.attributes.

Consulte Tipos de atributos OTLP para obtener detalles sobre los tipos de atributos compatibles con OTLP extremo New Relic y los límites de atributos OTLP para obtener detalles sobre la validación realizada en los atributos.

Enlaces de extensión

New Relic admite enlaces span de OpenTelemetry, que permiten crear relaciones causales entre intervalos que no tienen una conexión padre-hijo directa. Los enlaces de tramo son esenciales para comprender el rastreo distribuido que se divide en límites asincrónicos como cola de mensajes, flujos de eventos y sistemas de procesamiento por lotes.

Cuándo emplear enlaces span

Emplee enlaces span en los siguientes escenarios:

Message queue producers and consumers: Vincule un intervalo de consumo con el intervalo de producción al procesar mensajes de colas como AWS SQS, RabbitMQ o Kafka.
Fan-in patterns: Vincular múltiples trazas de productores a una única traza de consumidores que agregue sus productos.
Batch processing:Los enlaces abarcan los procesos de mensajes por lotes hasta su traza de origen individual.
Long-running workflows:Conecta tramos a través de pasos del flujo de trabajo que exceden los límites normales de duración del trazado.

Implementación de enlaces span

Para implementar enlaces span en su instrumentación OpenTelemetry, necesita:

Extraer contexto de traza del mensaje entrante o evento
Crear un enlace de intervalo al iniciar un nuevo intervalo en el consumidor
Cerciorar de que el contexto de traza se propague a través de su infraestructura de mensajería

Los siguientes ejemplos muestran cómo implementar enlaces span en 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

Para AWS SQS específicamente:

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");
    }
}

mejores prácticas para enlaces span

Al implementar enlaces de tramo, siga estas mejores prácticas:

Always propagate trace context:Cerciorar de que el contexto de seguimiento W3C (encabezados traceparent y tracestate) estén incluidos en los encabezados o metadatos del mensaje.
Validate span context:Siempre verifique si el contexto de intervalo extraído es válido antes de crear un enlace de intervalo. Los contextos no válidos no deben crear enlaces.
Use appropriate span kinds:Establezca el tipo PRODUCER para los intervalos de publicación de mensajes y el tipo CONSUMER para los intervalos de procesamiento de mensajes.
Add messaging attributes:Incluya convenciones semánticas para sistemas de mensajería (como messaging.system, messaging.destination, messaging.operation) para proporcionar contexto.
Consider sampling:Ambas trazas vinculadas deben muestrearse para que aparezcan en New Relic. Ajustar las estrategias de ejemplificación para flujos de trabajo críticos que emplean enlaces span.
Handle batch processing carefully:Al procesar mensajes por lotes, cree enlaces de intervalo individuales para cada mensaje para mantener la trazabilidad.

Visualización de enlaces span en New Relic

Una vez que implementó enlaces span en su instrumentación, puede verlos y navegar por ellos en la UI New Relic :

Vaya a la página de detalles de traza para obtener una traza
Busque la insignia de enlaces de tramo en la barra de filtro que muestra la cantidad de tramos con enlaces
Seleccione un lapso con enlaces para ver la pestaña Span links en el panel de detalles del lapso
Haga clic en el trazado vinculado para navegar entre los trazados relacionados

Para obtener información detallada sobre el uso de enlaces span en la UI, consulte Descripción de los enlaces span.

Te ofrecemos esta traducción automática para facilitar la lectura.

Mapeo de tramo OTLP

Notas a pie de tabla

Enlaces de extensión

Cuándo emplear enlaces span

Implementación de enlaces span

Python

Java

Node.js

Go

.NET

mejores prácticas para enlaces span

Visualización de enlaces span en New Relic

Te ofrecemos esta traducción automática para facilitar la lectura.

Trazas de OpenTelemetry en New Relic

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

Notas a pie de tabla

Enlaces de extensión

Cuándo emplear enlaces span

Implementación de enlaces span

Java

Node.js

Go

.NET

mejores prácticas para enlaces span

Visualización de enlaces span en New Relic

Mapeo de tramo OTLP