各编程语言的插桩示例
本节提供使用 AWS Application Signals 在不同编程语言和框架中插桩应用程序的指导。
演示应用程序
- Application Signals PetClinic Demo - 多语言 Spring Boot 微服务，包含全面的插桩示例
- One 可观测性 PetAdoptions Demo - 全栈应用程序，包含 Java、Python、.NET、Go、Rust 和 Node.js 服务
- CloudWatch Application Signals SkillBuilder Demo - 教育性示例，包含逐步插桩指南
自动插桩
自动插桩通过自动发现和插桩流行的框架和库来提供零代码的可观测性。这是快速开始使用 Application Signals 的推荐方法。
Java Spring Boot 应用程序
自动插桩设置：
java -javaagent:/path/to/aws-opentelemetry-agent.jar \
-Dotel.service.name=my-java-app \
-jar your-app.jar
参考微服务：
- PetClinic Demo：
- https://github.com/aws-samples/one-observability-demo/tree/main/src/applications/microservices/petsearch-java： Pet Search Service (Java)
Python 应用程序
自动插桩设置：
pip install pip install aws-opentelemetry-distro
opentelemetry-instrument \
--service_name my-python-app \
python your_app.py
参考微服务：
- One Observability Demo：
Node.js 应用程序
自动插桩设置：
npm install @aws/opentelemetry-auto-instrumentation
node --require @aws/opentelemetry-auto-instrumentation \
your_app.js
参考微服务：
- One Observability Demo (Lambda)：
.NET 应用程序
自动插桩设置：
// Configure in Program.cs
builder.Services.AddOpenTelemetry()
.WithTracing(builder => builder
.AddAspNetCoreInstrumentation()
.AddOtlpExporter());
参考微服务：
- PetClinic Demo： Payment Service (.NET)
- https://github.com/aws-samples/one-observability-demo/tree/main/src/applications/microservices/petsite-net： Pet Site Service (.NET)
手动插桩
手动插桩涉及完整的端到端 OpenTelemetry SDK 集成，不使用任何自动插桩 agent。这种方法提供了对遥测收集的最大控制，且是不支持自动插桩的语言所必需的。
Java — 手动 Spans
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Span;
Tracer tracer = GlobalOpenTelemetry.getTracer("my-service");
Span span = tracer.spanBuilder("custom-operation")
.setAttribute("user.id", userId)
.startSpan();
try {
// Your business logic
processOrder(order);
} finally {
span.end();
}
Python — 手动 Spans
from opentelemetry import trace
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("process-payment") as span:
span.set_attribute("payment.amount", amount)
span.set_attribute("payment.currency", currency)
result = process_payment(amount, currency)
span.set_attribute("payment.success", result.success)
.NET — 手动 Spans
using OpenTelemetry.Trace;
var tracer = tracerProvider.GetTracer("my-service");
using var span = tracer.StartActiveSpan("validate-user");
try
{
span.SetAttribute("user.email", user.Email);
var isValid = await ValidateUserAsync(user);
span.SetAttribute("validation.result", isValid);
return isValid;
}
catch (Exception ex)
{
span.SetStatus(Status.Error, ex.Message);
throw;
}
Node.js — 手动 Spans
const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('my-service');
async function processOrder(order) {
const span = tracer.startSpan('process-order');
span.setAttribute('order.id', order.id);
span.setAttribute('order.amount', order.amount);
try {
await validateOrder(order);
await chargePayment(order);
span.setAttribute('order.status', 'completed');
} catch (error) {
span.setStatus({ code: trace.SpanStatusCode.ERROR, message: error.message });
throw error;
} finally {
span.end();
}
}
Go 应用程序（仅手动）
Go 需要手动插桩（没有可用的自动插桩）。
import (
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
)
tracer := otel.Tracer("my-service")
_, span := tracer.Start(ctx, "process-request")
span.SetAttributes(
attribute.String("user.id", userID),
attribute.Float64("request.duration", duration),
)
defer span.End()
参考实现：
Rust 应用程序（仅手动）
参考实现：
组合插桩（自动 + 手动）
组合插桩使用自动插桩 agent 获取基线遥测数据，同时通过手动插桩添加自定义 spans、属性和业务上下文。
参考实现：
手动插桩关键最佳实践
- 业务上下文： 始终向 spans 添加相关业务属性（customer_id、order_value、product_category）
- 错误处理： 记录异常并设置适当的 span 状态码
- 自定义 Metrics： 在技术 metrics 之外创建业务特定的 metrics
- Span 层次结构： 使用子 spans 分解复杂操作
- 属性命名： 尽可能遵循 OpenTelemetry 语义约定
- 性能影响： 注意高吞吐量路径中插桩的开销