Instrumentation Samples for Various Programming Languages

This section provides guidance for instrumenting applications with AWS Application Signals across different programming languages and frameworks.

Demo Applications

• Application Signals PetClinic Demo - Multi-language Spring Boot microservices with comprehensive instrumentation examples
• One Observability PetAdoptions Demo - Full-stack application with Java, Python, .NET, Go, Rust, and Node.js services
• CloudWatch Application Signals SkillBuilder Demo - Educational examples with step-by-step instrumentation guides

Auto-Instrumentation

Auto-instrumentation provides zero-code observability by automatically detecting and instrumenting popular frameworks and libraries. This is the recommended approach for getting started quickly with Application Signals.

Java Spring Boot Applications

Auto-Instrumentation Setup:

java -javaagent:/path/to/aws-opentelemetry-agent.jar \
     -Dotel.service.name=my-java-app \
     -jar your-app.jar

Reference Microservices:

• PetClinic Demo:
  • API Gateway Service
  • Customers Service
  • Vets Service
  • Visits Service
• One Observability Demo: Pet Search Service (Java)

Python Applications

Auto-Instrumentation Setup:

pip install pip install aws-opentelemetry-distro
opentelemetry-instrument \
    --service_name my-python-app \
    python your_app.py

Reference Microservices:

• One Observability Demo:
  • Pet List Adoptions Service (Python)
  • Pet Food Agent - Strands (Python)

Node.js Applications

Auto-Instrumentation Setup:

npm install @aws/opentelemetry-auto-instrumentation
node --require @aws/opentelemetry-auto-instrumentation \
     your_app.js

Reference Microservices:

• One Observability Demo (Lambda):
  • Pet Status Updater (Node.js Lambda)
  • Pet Food Stock Processor (Node.js Lambda)
  • Pet Food Cleanup Processor (Node.js Lambda)
  • Traffic Generator (Node.js Lambda)

.NET Applications

Auto-Instrumentation Setup:

// Configure in Program.cs
builder.Services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddAspNetCoreInstrumentation()
        .AddOtlpExporter());

Reference Microservices:

• PetClinic Demo: Payment Service (.NET)
• One Observability Demo: Pet Site Service (.NET)

Manual Instrumentation

Manual instrumentation involves complete end-to-end integration of OpenTelemetry SDKs without any auto-instrumentation agents. This approach provides maximum control over telemetry collection and is required for languages that don't support auto-instrumentation.

Java — Manual 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 — Manual 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 — Manual 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 — Manual 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 Applications (Manual Only)

Go requires manual instrumentation (no auto-instrumentation available).

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()

Reference Implementation:

• Pay for Adoption Service (Go)

Rust Applications (Manual Only)

Reference Implementation:

• Pet Food Service (Rust)

Combined Instrumentation (Auto + Manual)

Combined instrumentation uses auto-instrumentation agents for baseline telemetry while adding custom spans, attributes, and business context through manual instrumentation.

Reference Implementations:

• Customers Service (Java)
• Pet Search Service (Java)

Key Manual Instrumentation Best Practices

• Business Context: Always add relevant business attributes (customer_id, order_value, product_category) to spans
• Error Handling: Record exceptions and set appropriate span status codes
• Custom Metrics: Create business-specific metrics alongside technical metrics
• Span Hierarchy: Use child spans to break down complex operations
• Attribute Naming: Follow OpenTelemetry semantic conventions where possible
• Performance Impact: Be mindful of instrumentation overhead in high-throughput paths