如何为Micronaut配置New Relic OpenTelemetry并实现自定义Span

问题核心诊断 #

你能在New Relic看到基础追踪数据，说明OpenTelemetry的基础导出链路是通的，但自定义Span没出现，大概率是缺少Micronaut注解追踪的集成依赖，或者配置未开启注解支持，也可能是注解使用不符合要求。

关键修复要点 #

1. 必须引入Micronaut OpenTelemetry的注解集成依赖
2. 配置文件中明确开启OpenTelemetry注解支持
3. 自定义Span注解需应用在public方法上（Micronaut代理仅拦截public方法）

完整示例项目实现 #

1. 依赖配置（Gradle） #

plugins {
    id("io.micronaut.application") version "4.3.4"
    id("java")
}

version "0.1"
group "com.example"

repositories {
    mavenCentral()
}

dependencies {
    // Micronaut OpenTelemetry核心依赖
    implementation("io.micronaut.tracing:micronaut-tracing-opentelemetry")
    // 注解支持依赖（必须加，否则@NewSpan等注解无效）
    implementation("io.micronaut.tracing:micronaut-tracing-opentelemetry-annotation")
    // OTLP导出器（New Relic支持OTLP协议）
    implementation("io.opentelemetry:opentelemetry-exporter-otlp")
    // OpenTelemetry自动配置扩展
    runtimeOnly("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
    runtimeOnly("ch.qos.logback:logback-classic")
}

micronaut {
    runtime("netty")
    testRuntime("junit5")
    processing {
        incremental(true)
        annotations("com.example.*")
    }
}

2. 配置文件（application.yml） #

micronaut:
  application:
    name: micronaut-otel-demo
opentelemetry:
  service:
    name: micronaut-otel-demo # New Relic中显示的服务名称
  exporter:
    otlp:
      endpoint: "https://otlp.nr-data.net:4317" # New Relic OTLP端点
      headers:
        api-key: "YOUR_NEW_RELIC_LICENSE_KEY" # 替换为你的New Relic密钥
  traces:
    sampler:
      type: always_on # 采样率设为100%，方便测试
tracing:
  opentelemetry:
    enabled: true
    annotation:
      enabled: true # 必须开启注解支持

3. 业务代码实现 #

控制器类

package com.example;

import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.tracing.annotation.NewSpan;
import io.micronaut.tracing.annotation.SpanTag;

@Controller("/demo")
public class DemoController {

    private final DemoService demoService;

    public DemoController(DemoService demoService) {
        this.demoService = demoService;
    }

    @Get("/{name}")
    @NewSpan("demo-controller-greet") // 自定义Span名称
    public String greet(@SpanTag("user.name") String name) { // 给Span添加标签
        return demoService.generateGreeting(name);
    }
}

服务类

package com.example;

import io.micronaut.tracing.annotation.NewSpan;
import io.micronaut.tracing.annotation.SpanTag;
import jakarta.inject.Singleton;

@Singleton
public class DemoService {

    @NewSpan("demo-service-generate-greeting")
    public String generateGreeting(@SpanTag("user.name") String name) {
        // 模拟业务耗时操作
        try {
            Thread.sleep(100);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return "Hello, " + name + "!";
    }
}

验证步骤 #

1. 替换配置文件中的YOUR_NEW_RELIC_LICENSE_KEY为你的New Relic密钥
2. 启动应用，访问http://localhost:8080/demo/Alice
3. 登录New Relic控制台，进入Traces页面，就能看到demo-controller-greet和demo-service-generate-greeting两个自定义Span，且带有user.name标签

常见排查点 #

• 确认micronaut-tracing-opentelemetry-annotation依赖已添加，没有这个依赖注解不会生效
• 检查tracing.opentelemetry.annotation.enabled是否设为true
• 自定义Span注解必须用在public方法上，私有/保护方法无法被代理拦截
• 验证OTLP端点和API密钥是否正确，可通过日志排查导出是否有错误

内容的提问来源于stack exchange，提问作者CraftyFella