Linkerd distributed tracing com OpenTelemetry

O Linkerd 2.19 e versões posteriores podem exportar um span para cada solicitação com proxy diretamente do sidecar da malha, sem a necessidade de configuração extra de backend de rastreamento ou cert-manager. Combinados com pods de aplicativo instrumentados, esses spans de proxy se conectam em traces de ponta a ponta que mostram exatamente como uma solicitação se moveu pela sua malha.

Como funciona

A ativação do tracing tem duas partes:

Exportação de trace no nível da malha: os proxies do Linkerd exportam um span por solicitação para o seu OTel Collector. Isso por si só fornece traces no nível do proxy (novas tentativas, handshakes mTLS, latência por salto) sem tocar no seu aplicativo.
Instrumentação do aplicativo: os pods do seu aplicativo propagam o mesmo W3C Trace Context que os proxies usam e exportam seus próprios spans. A combinação de ambos oferece uma cascata completa no mesmo trace: do aplicativo cliente, passando pelo proxy do Linkerd, até o aplicativo de backend.

Antes de você começar

Certifique-se de ter:

Linkerd edge-26.7.0 ou posterior (2.19+). O tracing de proxy em versões anteriores exigia um serviço de coletor separado e uma integração com o cert-manager, o que este guia não aborda. Consulte o guia de introdução do Linkerd se precisar atualizar.
NRDOT ou OTel Collector Contrib em execução para sua instância do Linkerd:
- Para o NRDOT, usando o chart do Helm ou o manifesto.
- Para o OTel Collector Contrib, usando o chart do Helm ou o manifesto.
Injeção ativada nos namespaces em que você deseja o trace.

Configurar o distributed tracing

Adicione um pipeline traces a deployment.configMap.extraConfig em seu values.yaml. Não redefina o receptor otlp. O chart já inclui um por padrão:

Processadores a adicionar:

k8sattributes/traces:
  auth_type: serviceAccount
  passthrough: false
  extract:
    metadata: [ k8s.deployment.name, k8s.node.name, k8s.namespace.name, k8s.pod.name ]
    labels:
      - { tag_name: linkerd_control_plane_ns, key: linkerd.io/control-plane-ns, from: pod }
      - { tag_name: linkerd_control_plane_component, key: linkerd.io/control-plane-component, from: pod }
  pod_association:
    - sources: [{ from: resource_attribute, name: k8s.pod.ip }]
    - sources: [{ from: connection }]

# Must run before transform/linkerd_service_name below.
transform/linkerd_component_inject:
  trace_statements:
    - context: span
      statements:
        - set(attributes["linkerd_control_plane_component"], "linkerd-proxy")
          where resource.attributes["service.name"] == "linkerd-proxy"
          and resource.attributes["linkerd_control_plane_ns"] != nil

# Renames service.name=linkerd-proxy to the correlated deployment name.
transform/linkerd_service_name:
  trace_statements:
    - context: resource
      statements:
        - set(attributes["service.name"], attributes["k8s.deployment.name"])
          where attributes["service.name"] == "linkerd-proxy"
          and attributes["k8s.deployment.name"] != nil

resourcedetection:
  detectors: [env]
  override: false

Pipelines a adicionar:

pipelines:
  traces:
    receivers: [otlp]
    processors: [memory_limiter, k8sattributes/traces, transform/linkerd_component_inject, transform/linkerd_service_name, resourcedetection, batch]
    exporters: [otlp_http/newrelic]

Importante

transform/linkerd_service_name torna o nome de cada implantação na malha o seu service.name do APM. Use nomes de implantação exclusivos em cada cluster que se reporta à mesma conta. Um nome que também existe em outro cluster é resolvido para a mesma entidade lá, de modo que seus dados são mesclados em vez de aparecerem como dois serviços separados.

Execute novamente o comando helm upgrade de Monitorar o Linkerd no Kubernetes com o OpenTelemetry com o values.yaml atualizado e, em seguida, conclua estas etapas únicas:

1. Adicione o coletor à malha. Os proxies do Linkerd só podem exportar trace para um coletor que esteja dentro da malha:

bash

$kubectl annotate namespace newrelic linkerd.io/inject=enabled
$kubectl rollout restart deployment/nr-k8s-otel-collector-deployment -n newrelic
$kubectl rollout restart daemonset/nr-k8s-otel-collector-daemonset -n newrelic

2. Marque a porta OTLP do coletor como gRPC. O serviço nr-k8s-otel-collector-gateway do chart não declara appProtocol em sua porta gRPC. Sem isso, a própria detecção de protocolo do Linkerd pode identificar incorretamente o tráfego para o coletor e descartar silenciosamente as exportações de trace dos proxies:

bash

$kubectl patch svc nr-k8s-otel-collector-gateway -n newrelic --type=json \
>  -p='[{"op":"add","path":"/spec/ports/1/appProtocol","value":"grpc"}]'

3. Ative o tracing nos proxies do Linkerd:

# linkerd-values.yaml
proxy:
  tracing:
    enabled: true
    collector:
      endpoint: nr-k8s-otel-collector-gateway.newrelic.svc.cluster.local:4317
      meshIdentity:
        serviceAccountName: nr-k8s-otel-collector
        namespace: newrelic

bash

$linkerd upgrade -f linkerd-values.yaml | kubectl apply -f -

bash

$linkerd upgrade \
>  --set proxy.tracing.enabled=true \
>  --set proxy.tracing.collector.endpoint=nr-k8s-otel-collector-gateway.newrelic.svc.cluster.local:4317 \
>  --set proxy.tracing.collector.meshIdentity.serviceAccountName=nr-k8s-otel-collector \
>  --set proxy.tracing.collector.meshIdentity.namespace=newrelic \
>  | kubectl apply -f -

bash

$kubectl rollout restart deployment -n <YOUR_NAMESPACE>

Em seguida, continue para Instrumentar os pods do aplicativo abaixo.

Adicione o seguinte ao mesmo deployment-configmap.yaml. Não redefina o receiver otlp. O manifesto base já inclui um por padrão:

Processadores a adicionar:

processors:
  k8sattributes/traces:
    auth_type: serviceAccount
    passthrough: false
    extract:
      metadata: [ k8s.deployment.name, k8s.node.name, k8s.namespace.name, k8s.pod.name ]
      labels:
        - { tag_name: linkerd_control_plane_ns, key: linkerd.io/control-plane-ns, from: pod }
        - { tag_name: linkerd_control_plane_component, key: linkerd.io/control-plane-component, from: pod }
    pod_association:
      - sources: [{ from: resource_attribute, name: k8s.pod.ip }]
      - sources: [{ from: connection }]

  # Must run before transform/linkerd_service_name below.
  transform/linkerd_component_inject:
    trace_statements:
      - context: span
        statements:
          - set(attributes["linkerd_control_plane_component"], "linkerd-proxy")
            where resource.attributes["service.name"] == "linkerd-proxy"
            and resource.attributes["linkerd_control_plane_ns"] != nil

  # Renames service.name=linkerd-proxy to the correlated deployment name.
  transform/linkerd_service_name:
    trace_statements:
      - context: resource
        statements:
          - set(attributes["service.name"], attributes["k8s.deployment.name"])
            where attributes["service.name"] == "linkerd-proxy"
            and attributes["k8s.deployment.name"] != nil

  resourcedetection:
    detectors: [env]
    override: false

Pipelines a adicionar:

pipelines:
  traces:
    receivers: [otlp]
    processors: [memory_limiter, k8sattributes/traces, transform/linkerd_component_inject, transform/linkerd_service_name, resourcedetection, batch]
    exporters: [otlp_http/newrelic]

Importante

Reaplique o ConfigMap acima e, em seguida, conclua estas etapas únicas:

1. Adicione o coletor à malha. Os proxies do Linkerd só podem exportar trace para um coletor que esteja dentro da malha:

bash

$kubectl annotate namespace newrelic linkerd.io/inject=enabled
$kubectl rollout restart deployment/nr-k8s-otel-collector-deployment -n newrelic
$kubectl rollout restart daemonset/nr-k8s-otel-collector-daemonset -n newrelic

2. Marque a porta OTLP do coletor como gRPC. O serviço nr-k8s-otel-collector-gateway renderizado não declara appProtocol em sua porta gRPC. Sem isso, a própria detecção de protocolo do Linkerd pode identificar incorretamente o tráfego para o coletor e descartar silenciosamente as exportações de trace dos proxies:

bash

$kubectl patch svc nr-k8s-otel-collector-gateway -n newrelic --type=json \
>  -p='[{"op":"add","path":"/spec/ports/1/appProtocol","value":"grpc"}]'

3. Ative o tracing nos proxies do Linkerd:

# linkerd-values.yaml
proxy:
  tracing:
    enabled: true
    collector:
      endpoint: nr-k8s-otel-collector-gateway.newrelic.svc.cluster.local:4317
      meshIdentity:
        serviceAccountName: nr-k8s-otel-collector
        namespace: newrelic

bash

$linkerd upgrade -f linkerd-values.yaml | kubectl apply -f -

bash

$linkerd upgrade \
>  --set proxy.tracing.enabled=true \
>  --set proxy.tracing.collector.endpoint=nr-k8s-otel-collector-gateway.newrelic.svc.cluster.local:4317 \
>  --set proxy.tracing.collector.meshIdentity.serviceAccountName=nr-k8s-otel-collector \
>  --set proxy.tracing.collector.meshIdentity.namespace=newrelic \
>  | kubectl apply -f -

bash

$kubectl rollout restart deployment -n <YOUR_NAMESPACE>

Em seguida, continue para Instrumentar os pods do aplicativo abaixo.

A partir do Linkerd 2.19, a exportação de trace de proxy é configurada diretamente no plano de controle, sem a necessidade de cert-manager ou porta separada. Duas etapas são necessárias: tornar o coletor capaz de receber trace e, em seguida, ativar a exportação de trace dos proxies.

Etapa 1: adicione a ingestão de trace ao coletor

Ao contrário do chart do NRDOT, o chart open-telemetry/opentelemetry-collector da comunidade não inclui um receptor otlp por padrão. Adicione-o explicitamente, junto com os mesmos processadores usados na guia NRDOT.

Adicione o seguinte à mesma seção config do seu values.yaml de OTel Collector Contrib com o Helm:

Receptores a adicionar:

otlp:
  protocols:
    grpc:
      endpoint: 0.0.0.0:4317
    http:
      endpoint: 0.0.0.0:4318

Processadores a adicionar:

k8sattributes/traces:
  auth_type: serviceAccount
  passthrough: false
  extract:
    metadata: [ k8s.deployment.name, k8s.node.name, k8s.namespace.name, k8s.pod.name ]
    labels:
      - { tag_name: linkerd_control_plane_ns, key: linkerd.io/control-plane-ns, from: pod }
      - { tag_name: linkerd_control_plane_component, key: linkerd.io/control-plane-component, from: pod }
  pod_association:
    - sources: [{ from: resource_attribute, name: k8s.pod.ip }]
    - sources: [{ from: connection }]

# Must run before transform/linkerd_service_name below.
transform/linkerd_component_inject:
  trace_statements:
    - context: span
      statements:
        - set(attributes["linkerd_control_plane_component"], "linkerd-proxy")
          where resource.attributes["service.name"] == "linkerd-proxy"
          and resource.attributes["linkerd_control_plane_ns"] != nil

# Renames service.name=linkerd-proxy to the correlated deployment name.
transform/linkerd_service_name:
  trace_statements:
    - context: resource
      statements:
        - set(attributes["service.name"], attributes["k8s.deployment.name"])
          where attributes["service.name"] == "linkerd-proxy"
          and attributes["k8s.deployment.name"] != nil

resourcedetection:
  detectors: [env]
  override: false

Pipelines a adicionar:

traces:
  receivers: [otlp]
  processors: [memory_limiter, k8sattributes/traces, transform/linkerd_component_inject, transform/linkerd_service_name, resourcedetection, batch]
  exporters: [otlp_http/newrelic]

Reaplique:

bash

$helm upgrade my-opentelemetry-collector open-telemetry/opentelemetry-collector -f values.yaml -n newrelic --create-namespace --install

Adicione os mesmos três blocos acima (Receivers, Processors, Pipelines) à chave config do ConfigMap no seu otel-collector.yaml de OTel Collector Contrib with manifest. O Service nesse manifesto já expõe a porta 4317 (grpc) e 4318 (http), portanto, nenhuma alteração de porta é necessária. Reaplique e reinicie. Reaplicar apenas o ConfigMap não reinicia o pod do coletor em execução, portanto, ele não adotará a nova configuração sem o segundo comando:

bash

$kubectl apply -f otel-collector.yaml
$kubectl rollout restart deployment/my-opentelemetry-collector -n newrelic

Etapa 2: ativar a exportação de trace do proxy

1. Adicione o coletor à malha. Os proxies do Linkerd só podem exportar traces para um coletor que esteja dentro da malha. Ao contrário do nr-k8s-otel-collector-gateway do chart do NRDOT, nada no manifesto do OTel Collector Contrib ou no chart do Helm injeta o pod do coletor na malha por padrão:

bash

$kubectl annotate namespace newrelic linkerd.io/inject=enabled
$kubectl rollout restart deployment/my-opentelemetry-collector -n newrelic

Importante

A seção meshIdentity abaixo é obrigatória. O Linkerd só pode exportar trace para um coletor que esteja dentro da malha, que é o que o comando acima acabou de fazer.

2. Ative o tracing nos proxies do Linkerd:

# values.yaml
proxy:
  tracing:
    enabled: true
    collector:
      endpoint: my-opentelemetry-collector.newrelic.svc.cluster.local:4317
      meshIdentity:
        serviceAccountName: my-opentelemetry-collector
        namespace: newrelic

bash

$helm upgrade linkerd-control-plane linkerd/linkerd-control-plane \
>  --namespace linkerd --reuse-values -f values.yaml

bash

$linkerd upgrade \
>  --set proxy.tracing.enabled=true \
>  --set proxy.tracing.collector.endpoint=my-opentelemetry-collector.newrelic.svc.cluster.local:4317 \
>  --set proxy.tracing.collector.meshIdentity.serviceAccountName=my-opentelemetry-collector \
>  --set proxy.tracing.collector.meshIdentity.namespace=newrelic \
>  | kubectl apply -f -

Etapa 3: reinicie os pods em malha do seu aplicativo

Isso é separado da reinicialização do coletor na Etapa 2 — aplica a nova configuração de tracing de proxy aos pods que você está realmente rastreando:

bash

$kubectl rollout restart deployment -n <YOUR_NAMESPACE>

Instrumente os pods do seu aplicativo

Adicione o agente Java do OTel (ou o agente para sua linguagem) para propagar os cabeçalhos de contexto do trace. O Linkerd suporta os formatos W3C Trace Context e B3. O agente OTel trata isso automaticamente.

Dica

spec.exporter.endpoint abaixo aponta para o Service da página OTel Collector Contrib with manifest. Se você implantou o coletor NRDOT, use http://nr-k8s-otel-collector-gateway.newrelic.svc.cluster.local:4317 em vez disso.

bash

$kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml
$
$kubectl apply -f - <<'EOF'
$apiVersion: opentelemetry.io/v1alpha1
$kind: Instrumentation
$metadata:
$  name: nr-instrumentation
$  namespace: <YOUR_NAMESPACE>
$spec:
$  exporter:
$    endpoint: http://my-opentelemetry-collector.newrelic.svc.cluster.local:4317
$  propagators: [tracecontext, baggage]
$  java:
$    image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
$EOF
$
$kubectl annotate deployment <YOUR_DEPLOYMENT> \
>  instrumentation.opentelemetry.io/inject-java="true" \
>  -n <YOUR_NAMESPACE>

Para outras linguagens (Python, .NET, Node.js, Go) e configuração avançada do Operator, como injeção de sidecar vs. init-container, limites de recursos ou pods de vários contêineres, consulte a documentação de instrumentação automática do OpenTelemetry Operator.

Correlacionar métricas do aplicativo com o APM (opcional)

Se o seu aplicativo também exporta métrica do OTel SDK (não apenas trace) para o coletor, adicione o seguinte para roteá-la para um pipeline de métrica compatível com APM.

Processadores a adicionar:

metricstransform/apm_compat:
  transforms:
    - include: http.server.request.duration
      action: insert
      new_name: apm.service.transaction.duration

Pipelines a adicionar:

metrics/otlp:
  receivers: [otlp]
  processors: [memory_limiter, resourcedetection, transform/metadata_nullify, metricstransform/apm_compat, batch]
  exporters: [otlp_http/newrelic]

Adicione ambos a qualquer configuração de coletor que você implantou e, em seguida, reaplique-a:

Se você implantou	Adicione à	Reaplique com
NRDOT - Helm	`deployment.configMap.extraConfig` no seu `values.yaml`	`helm upgrade nr-k8s-otel-collector newrelic/nr-k8s-otel-collector --namespace newrelic --reuse-values -f values.yaml`
NRDOT - Manifesto	`deployment-configmap.yaml`	`kubectl apply -f rendered/deployment-configmap.yaml -n newrelic && kubectl rollout restart deployment -n newrelic`
OTel Collector Contrib - Helm	a seção `config` do seu `values.yaml`	`helm upgrade my-opentelemetry-collector open-telemetry/opentelemetry-collector -f values.yaml -n newrelic --create-namespace --install`
OTel Collector Contrib - Manifesto	chave `config` do ConfigMap em `otel-collector.yaml`	`kubectl apply -f otel-collector.yaml && kubectl rollout restart deployment/my-opentelemetry-collector -n newrelic`

Colete logs do proxy do Linkerd

Opcionalmente, colete os logs do contêiner sidecar

linkerd-proxy

Referência de métricas

Lista completa de métricas e atributos de recursos do Linkerd coletados pelo OTel Collector.

Encontre e consulte seus dados

Passo a passo do dashboard, consultas NRQL e etapas de resolução de problemas.

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

Linkerd distributed tracing com OpenTelemetry

Como funciona

Antes de você começar

Configurar o distributed tracing

Instalação via Helm

Importante

Via Helm

Alternativa: Linkerd CLI

Instalação via manifesto

Importante

Via Helm

Alternativa: Linkerd CLI

Etapa 1: adicione a ingestão de trace ao coletor

Leme

Manifesto

Etapa 2: ativar a exportação de trace do proxy

Importante

Via Helm

Alternativa: Linkerd CLI

Etapa 3: reinicie os pods em malha do seu aplicativo

Instrumente os pods do seu aplicativo

Dica

OTel Operator (recomendado)

Correlacionar métricas do aplicativo com o APM (opcional)

Colete logs do proxy do Linkerd

Referência de métricas

Encontre e consulte seus dados

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

Linkerd distributed tracing com OpenTelemetry

Como funciona .css-21sua1{background:none;border:none;width:0;padding:0;}

Antes de você começar

Configurar o distributed tracing

Instalação via manifesto

Etapa 1: adicione a ingestão de trace ao coletor

Leme

Manifesto

Etapa 2: ativar a exportação de trace do proxy

Importante

Via Helm

Alternativa: Linkerd CLI

Etapa 3: reinicie os pods em malha do seu aplicativo

Instrumente os pods do seu aplicativo

Dica

OTel Operator (recomendado)

Correlacionar métricas do aplicativo com o APM (opcional)

Artigos relacionados

Colete logs do proxy do Linkerd

Referência de métricas

Encontre e consulte seus dados

Como funciona