뉴렐릭의 OpenTelemetry 트레이스

OpenTelemetry 기록용 API , 범위 데이터 내보내기용 SDK , 경계를 넘나드는 추적을 위한 예외 없이 풍부한 추적 생태계를 제공합니다.

이 페이지에서는 뉴렐릭이 뉴렐릭 OTLP 엔드포인트를 통해 수신한 OpenTelemetry 범위를 처리하는 방법을 설명합니다. OpenTelemetry 트레이스를 뉴렐릭으로 보내려면 OTLP 엔드포인트를 통해 뉴렐릭 OpenTelemetry 수집기로 데이터를 내보내도록 트레이스 소스를 구성해야 합니다. 다음 페이지를 참조하세요.

엔드포인트 설정 요구 사항은 뉴렐릭 OTLP 엔드포인트를 참조하세요.
OpenTelemetry를 사용하여 서비스를 구성하는 방법에 대한 자세한 내용은 OpenTelemetry APM 모니터링을 참조하세요.

OTLP 범위 매핑

뉴렐릭은 OTLP 스팬을 Span 데이터 유형에 매핑합니다. 아래 표는 트레스의 proto 메시지 정의 의 필드가 해석되는 방식을 설명합니다.

OTLP 프로토 필드	뉴렐릭 `Span` 필드
`ResourceSpans.Resource.attributes`	각 핵심 가치는 `Span` [1]의 속성입니다.
`ScopeSpans.InstrumentationScope.name`	`otel.library.name`
`ScopeSpans.InstrumentationScope.version`	`otel.library.version`
`ScopeSpans.InstrumentationScope.attributes`	각 핵심 가치는 `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` `Span.start_time_unix_nano`) 사용하는 컴퓨터
`Span.attributes`	각 핵심 가치는 `Span` [1]의 속성입니다.
`Span.dropped_attribute_count`	`otel.dropped_attributes_count`
`Span.events`	각 이벤트는 소스 범위를 참조하는 `span.id` / `trace.id` 가 포함된 `SpanEvent` 로 기록되며 개수는 다음과 같이 저장됩니다. `nr.spanEventCount`
`Span.events[*].time_unix_nano`	에 `timestamp` 로 저장됨 `SpanEvent`
`Span.events[*].name`	에 `name` 로 저장됨 `SpanEvent`
`Span.events[*].attributes`	각 핵심 가치는 속성으로 저장됩니다. `SpanEvent`
`Span.events[*].dropped_attributes_count`	에 `ote.dropped_Attributes_count` 로 저장됨 `SpanEvent`
`Span.dropped_events_count`	`otel.dropped_events_count`
`Span.status.message`	`otel.status_description`
`Span.status.code`	`otel.status_code`

표 각주

[1] 리소스 속성, 범위 속성, 범위 속성 및 최상위 범위 필드에서 충돌이 발생하는 경우 우선순위(가장 높은 순서에서 가장 낮은 순서)는 최상위 Span.* 필드 > Span.attributes > ScopeSpans.InstrumentationScope.attributes > ResourceSpans.Resource.attributes 입니다.

뉴웰릭 OTLP 엔드포인트 지원 속성 유형 에 대한 자세한 내용은 OTLP 속성 유형을 참조하고 속성에 대해 수행되는 유효성 검사에 대한 자세한 내용은 OTLP 속성 제한을 참조하세요 .

스팬 링크

뉴렐릭은 OpenTelemetry 스팬 링크를 지원합니다. 이를 통해 직접적인 부모-자식 연결이 없는 스팬 간에 인과 관계를 생성할 수 있습니다. 스팬 링크는 포인터, 이벤트 스트림 및 일괄 처리 시스템과 같은 프로세서 경계를 넘어 분할되는 독립 트레이스를 이해하는 데 필수적입니다.

span 링크는 언제 사용해야 할까요?

다음과 같은 상황에서 span 링크를 사용하십시오.

Message queue producers and consumersAWS SQS, RabbitMQ 또는 Kafka와 같은 큐에서 메시지를 처리할 때 소비 스팬을 생산 스팬에 연결합니다.
Fan-in patterns: 여러 생산자 트레이를 출력을 집계하는 단일 소비자 트레이에 연결합니다.
Batch processing: 일괄 처리된 메시지를 개별 발신지로 되돌려 보내는 링크 범위입니다.
Long-running workflows: 일반적인 트레이스 지속 시간 제한을 초과하는 워크플로우 단계에 걸쳐 스팬을 연결합니다.

스팬 링크 구현

OpenTelemetry 측정 및 계측에서 스팬 링크를 구현하려면 다음이 필요합니다.

들어오는 메시지 또는 이벤트에서 트레이스 섹션을 추출합니다.
컨슈머에서 새 스팬을 시작할 때 스팬 링크를 생성합니다.
트레이스 컨텍스트가 메시징을 통해 전파되는지 확인하세요.

다음 예시들은 다양한 언어에서 스팬 링크를 구현하는 방법을 보여줍니다.

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

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

span 링크 사용 모범 사례

스팬 링크를 구현할 때는 다음 모범 사례를 따르세요.

Always propagate trace context: 메시지 헤더에 W3C 추적 컨텍스트(traceparent 및 tracestate 헤더)가 포함되어 있는지 확인하거나,
Validate span context스팬 링크를 생성하기 전에 추출된 스팬 컨텍스트가 유효한지 항상 확인하십시오. 유효하지 않은 컨텍스트에서는 링크가 생성되어서는 안 됩니다.
Use appropriate span kinds메시지 게시 기간에는 PRODUCER 유형을, 메시지 처리 기간에는 CONSUMER 유형을 설정합니다.
Add messaging attributes: 메시지 시스템에 대한 의미 규칙(예: messaging.system, messaging.destination, messaging.operation)을 포함하여 컨텍스트를 제공합니다.
Consider sampling: 링크된 두 트레이스가 모두 샘플링되어야 뉴렐릭에 나타납니다. 스팬 링크를 사용하는 중요한 샘플링 전략을 조정합니다.
Handle batch processing carefully일괄 메시지를 처리할 때는 추적성을 유지하기 위해 각 메시지에 대해 개별 스팬 링크를 생성하십시오.

뉴럴릭에서 span 링크 보기

측정, 계측에 스팬 링크를 구현하면 뉴럴릭 UI 에서 해당 링크를 보고 탐색할 수 있습니다.

aTrays의 트레이스 세부정보 페이지 로 이동하세요.
링크가 포함된 스팬의 수를 보여주는 필터 바에서 '스팬 링크' 배지를 찾아보세요.
링크가 포함된 스팬을 선택하면 스팬 세부 정보 창에서 Span links 탭이 표시됩니다.
관련 트레이스를 탐색하려면 연결된 트레이스를 클릭하세요.

UI에서 스팬 링크를 사용하는 방법에 대한 자세한 내용은 스팬 링크 이해를 참조하세요.

사용자의 편의를 위해 제공되는 기계 번역입니다.

뉴렐릭의 OpenTelemetry 트레이스

OTLP 범위 매핑

표 각주

스팬 링크

span 링크는 언제 사용해야 할까요?

스팬 링크 구현

파이썬

자바

노드.js

가다

.그물

span 링크 사용 모범 사례

뉴럴릭에서 span 링크 보기

사용자의 편의를 위해 제공되는 기계 번역입니다.

뉴렐릭의 OpenTelemetry 트레이스

OTLP 범위 매핑 .css-21sua1{background:none;border:none;width:0;padding:0;}

표 각주

스팬 링크

span 링크는 언제 사용해야 할까요?

스팬 링크 구현

자바

노드.js

가다

.그물

span 링크 사용 모범 사례

뉴럴릭에서 span 링크 보기

OTLP 범위 매핑