将 Litefuse 与 Quarkus LangChain4j 集成
本指南介绍如何使用 OpenTelemetry 将 Litefuse 与 Quarkus LangChain4j 集成。
Quarkus LangChain4j：基于 Quarkus 的 LangChain4j 集成，用于 AI 开发，并内置了对 AI 调用的 OTel 追踪。
Litefuse：开源的 AI Agent 可观测性与评估平台，提供可观测性、评估和 prompt 管理能力。
如果在此集成中遇到任何问题，请在 GitHub 上提交 Issue。
第 1 步：在 Quarkus LangChain4j 中启用 OpenTelemetry
添加 Quarkus OpenTelemetry 依赖（Maven）：
Maven 用户请在 pom.xml 中添加以下内容（Gradle 用户可使用等价的 Gradle 配置）：
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-opentelemetry</artifactId>
</dependency>配置 OpenTelemetry exporter（application.properties）：
quarkus.otel.exporter.otlp.traces.protocol=http/protobuf配置好这些依赖与设置后，你的 Quarkus 应用就可以产出 OpenTelemetry trace 数据了。Quarkus LangChain4j 的内部调用（例如调用 chat 模型）会被记录为 span。
每个 span 都会带有诸如 gen_ai.operation.name、gen_ai.system（提供商，例如 “openai”）、模型名、token 使用量等属性。
若要为 prompt 与响应内容启用事件，你需要打开 langchain4j 的 prompt 追踪。
配置 Langchain4j prompt 追踪（application.properties）：
quarkus.langchain4j.tracing.include-prompt=true
quarkus.langchain4j.tracing.include-completion=true第 2 步：配置 Litefuse
现在你的 Quarkus 应用已经在产出 OpenTelemetry trace 数据，下一步就是把这些数据导向 Litefuse。
在这一套配置中，Litefuse 充当 OpenTelemetry 的 “后端” —— 本质上是用 Litefuse 的 trace 摄入 API 替代了常见的 Jaeger/Zipkin/OTel Collector。
Litefuse 配置
- 注册 Litefuse Cloud 或选择自托管 Litefuse。
- 设置 OTLP endpoint（例如
https://litefuse.cloud/api/public/otel）和 API Key。
通过环境变量配置：
QUARKUS_OTEL_EXPORTER_OTLP_ENDPOINT: 设置为 Litefuse 的 OTLP URL（例如 https://litefuse.cloud/api/public/otel）。
QUARKUS_OTEL_EXPORTER_OTLP_HEADERS: 设置为 Authorization=Basic <base64 public:secret>。关于 Basic Auth 认证的更多信息，请参见这里。
第 3 步：运行一次测试 AI 操作
启动你的 Quarkus 应用。触发一次由 Quarkus LangChain4j 处理的 AI 操作 —— 例如调用一个使用 ChatModel 生成补全的 service 或 controller。
注意：完整示例可在这里查看。
@RegisterAiService(tools = EmailService.class)
public interface MyAiService {
/**
* Ask the LLM to create a poem about the given topic.
*
* @param topic the topic of the poem
* @param lines the number of line of the poem
* @return the poem
*/
@SystemMessage("You are a professional poet")
@UserMessage("""
Write a single poem about {topic}. The poem should be {lines} lines long and your response should only include the poem itself, nothing else.
Then send this poem by email. Your response should include the poem.
""")
String writeAPoem(String topic, int lines);
}
@Singleton
public class Startup {
public void writeAPoem(@Observes StartupEvent event, MyAiService service) {
System.out.println(service.writeAPoem("Langfuse", 4));
}
}故障排查
没有 trace：
- 查看应用日志，寻找可能的线索
- 参考故障排查页面