0Pricing
System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) · Leçon

Bonnes pratiques de l’instrumentation manuelle

Comprenez quand et comment appliquer une instrumentation manuelle pour contrôler précisément vos données d’observabilité. Apprenez à enrichir les traces avec des attributs personnalisés.

Bonnes pratiques de l’instrumentation manuelle est une leçon System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry), et ta progression se synchronise sur le web et l'application CoddyKit. Le cours System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) comprend 4 leçons au total.

Certaines parties de cette leçon n'ont pas encore été traduites et s'affichent en anglais.

Manual Instrumentation Intro

Welcome! In this lesson, we'll dive into manual instrumentation with OpenTelemetry. While auto-instrumentation is great for quick wins, manual control gives you precision.

Manual instrumentation allows you to record highly specific details about your application's internal operations. This is crucial for debugging complex business logic or custom components.

Why Manual Over Auto?

Auto-instrumentation automatically collects data from common libraries and frameworks. However, it can't know your unique application logic.

  • Custom Logic: Instrument specific functions or blocks of code.
  • Business Context: Add attributes relevant to your business domain.
  • Fine-Grained Control: Define exact span boundaries and relationships.
  • Missing Coverage: Cover areas where auto-instrumentation doesn't reach.

Creating Your First Span

A span represents a single operation within a trace. To create one manually, you need a Tracer, which is obtained from the OpenTelemetry SDK.

Here's how to start a new span. Remember to always end your spans!

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.SpanBuilder;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class ManualSpanDemo {
  public static void main(String[] args) {
    // Setup OpenTelemetry SDK (simplified for demo)
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    // Start a new span
    Span span = tracer.spanBuilder("MyCustomOperation").startSpan();

    try {
      System.out.println("Executing custom operation...");
      // Simulate work
      Thread.sleep(100);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      // Always end the span!
      span.end();
      System.out.println("Span ended.");
    }
  }
}

Activating Spans with Scope

For a span to be part of the current trace context (and for child spans to automatically link to it), it needs to be active. The best way to manage this is using a Scope with a try-with-resources statement.

This ensures the span is automatically set as active and ended when the block exits.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class ActiveSpanDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span parentSpan = tracer.spanBuilder("ParentOperation").startSpan();
    try (Scope parentScope = parentSpan.makeCurrent()) { // Parent span is active
      System.out.println("Parent operation started.");

      Span childSpan = tracer.spanBuilder("ChildOperation").startSpan(); // Automatically links to parent
      try (Scope childScope = childSpan.makeCurrent()) {
        System.out.println("Child operation executing...");
        Thread.sleep(50);
      } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
      } finally {
        childSpan.end();
        System.out.println("Child operation ended.");
      }

      Thread.sleep(50);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      parentSpan.end();
      System.out.println("Parent operation ended.");
    }
  }
}

Adding Custom Attributes

Attributes are key-value pairs that provide contextual information about a span. They are vital for making your traces searchable and understandable.

You can add attributes to a span using span.setAttribute(). Use descriptive keys and relevant values.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class SpanAttributesDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span span = tracer.spanBuilder("ProcessOrder").startSpan();
    try (Scope scope = span.makeCurrent()) {
      System.out.println("Processing order...");
      // Add attributes for order details
      span.setAttribute("order.id", "XYZ789");
      span.setAttribute("customer.email", "user@example.com");
      span.setAttribute(AttributeKey.longKey("item.count"), 3L);

      Thread.sleep(150);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      span.end();
      System.out.println("Order processed. Span ended with attributes.");
    }
  }
}

Recording Span Events

Events are timestamped messages associated with a span. They are useful for marking significant moments or logging specific actions that occur during the span's lifetime, without creating new child spans.

Think of them as mini-logs within your trace, adding more detail to a specific operation.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class SpanEventsDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span span = tracer.spanBuilder("UserLogin").startSpan();
    try (Scope scope = span.makeCurrent()) {
      System.out.println("User login initiated...");
      span.addEvent("AuthenticationStarted");

      Thread.sleep(80);
      // Add an event with attributes
      span.addEvent("DatabaseCheck", Attributes.of(
          AttributeKey.stringKey("db.query"), "SELECT * FROM users WHERE id=?"
      ));

      Thread.sleep(70);
      span.addEvent("AuthenticationSuccessful");

    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      span.end();
      System.out.println("User login span ended with events.");
    }
  }
}

Handling Errors in Spans

It's crucial to mark spans as failed when an error occurs. This helps quickly identify problematic operations in your system.

You can set a span's status to ERROR and record the exception that caused the failure. This provides rich context for debugging.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Scope;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class SpanErrorDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    Span span = tracer.spanBuilder("CriticalFunction").startSpan();
    try (Scope scope = span.makeCurrent()) {
      System.out.println("Executing critical function...");
      // Simulate an error condition
      if (Math.random() > 0.5) {
        throw new RuntimeException("Simulated critical failure!");
      }
      System.out.println("Critical function completed successfully.");

    } catch (Exception e) {
      System.out.println("Error caught: " + e.getMessage());
      span.setStatus(StatusCode.ERROR, "Function failed");
      span.recordException(e);
    } finally {
      span.end();
      System.out.println("Critical function span ended.");
    }
  }
}

Best Practices for Spans

To get the most out of manual instrumentation, follow these guidelines:

  • Granularity: Create spans for meaningful units of work, not every single line of code.
  • Meaningful Names: Use clear, low-cardinality names (e.g., user.login, db.query).
  • Rich Attributes: Add relevant business and technical context as attributes.
  • Always End Spans: Use try-with-resources or explicit span.end() in a finally block.
  • Avoid Over-instrumentation: Too many spans can add overhead. Focus on critical paths.

Linking Spans Explicitly

While makeCurrent() handles most parent-child linking, sometimes you need to explicitly link spans. This is common in asynchronous scenarios or when integrating with non-instrumented systems.

You can use SpanBuilder.setParent() or setNoParent() to control the parent-child relationship.

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.SpanContext;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.TraceFlags;
import io.opentelemetry.api.trace.TraceState;
import io.opentelemetry.context.Context;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;

public class ExplicitLinkDemo {
  public static void main(String[] args) {
    SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
    OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
        .setTracerProvider(sdkTracerProvider)
        .buildAndRegisterGlobal();

    Tracer tracer = openTelemetry.getTracer("my-app", "1.0.0");

    // Imagine a span from an external system, represented by its context
    SpanContext externalContext = SpanContext.create(
        "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d", // Trace ID
        "0000000000000001", // Span ID
        TraceFlags.getDefault(), TraceState.getDefault()
    );

    // Create a new span that links to this external context
    Span linkedSpan = tracer.spanBuilder("ProcessingExternalMessage")
        .setParent(Context.current().with(Span.wrap(externalContext))) // Link to external context
        .setSpanKind(SpanKind.CONSUMER) // Indicate it's a message consumer
        .startSpan();

    try {
      System.out.println("Processing message from external system...");
      linkedSpan.setAttribute("message.id", "MSG-123");
      Thread.sleep(100);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    } finally {
      linkedSpan.end();
      System.out.println("Linked span ended.");
    }
  }
}

Manual Instrumentation Check

You're implementing a new feature that calculates a user's loyalty points. You want to instrument this specific calculation to track its duration and the final points awarded. Which of the following is the most appropriate way to record the final points using manual OpenTelemetry instrumentation?

Recap: Manual Control

In this lesson, we explored manual instrumentation with OpenTelemetry. You learned:

  • When to choose manual over auto-instrumentation for fine-grained control.
  • How to create, activate, and end spans.
  • The power of attributes for adding rich context to your traces.
  • How to use events to mark specific moments within a span.
  • Best practices for handling errors and linking spans explicitly.

Mastering manual instrumentation gives you unparalleled visibility into your application's unique logic and performance.

Questions Fréquemment Posées

La leçon « Bonnes pratiques de l’instrumentation manuelle » est-elle gratuite ?

Oui — le texte complet de « Bonnes pratiques de l’instrumentation manuelle » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry), passe à CoddyKit PRO. Le cours System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Bonnes pratiques de l’instrumentation manuelle » ?

Comprenez quand et comment appliquer une instrumentation manuelle pour contrôler précisément vos données d’observabilité. Apprenez à enrichir les traces avec des attributs personnalisés. Tu pratiques System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) ?

Aucune expérience préalable n'est requise. System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Bonnes pratiques de l’instrumentation manuelle » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) ?

Oui. Chaque leçon System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

  1. Techniques d’instrumentation automatique
  2. Bonnes pratiques de l’instrumentation manuelle
  3. Propagation du contexte et bagages
  4. Attributs, événements et état des spans
← Retour à System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)