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

Najlepsze praktyki instrumentacji ręcznej

Zrozum, kiedy i jak stosować instrumentację ręczną, aby uzyskać szczegółową kontrolę nad danymi obserwowalności. Naucz się wzbogacać ślady o niestandardowe atrybuty.

Najlepsze praktyki instrumentacji ręcznej to bezpłatna lekcja System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry), a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) zawiera 4 lekcji w sumie.

Części tej lekcji nie zostały jeszcze przetłumaczone i są wyświetlane po angielsku.

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.

Często zadawane pytania

Czy lekcja „Najlepsze praktyki instrumentacji ręcznej” jest bezpłatna?

Tak — pełny tekst „Najlepsze praktyki instrumentacji ręcznej” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry), przejdź na CoddyKit PRO. Kurs System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) zawiera 4 lekcji w sumie.

Co nauczysz się w „Najlepsze praktyki instrumentacji ręcznej”?

Zrozum, kiedy i jak stosować instrumentację ręczną, aby uzyskać szczegółową kontrolę nad danymi obserwowalności. Naucz się wzbogacać ślady o niestandardowe atrybuty. Ćwiczysz System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)?

Nie wymagamy żadnego doświadczenia. System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Najlepsze praktyki instrumentacji ręcznej”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)?

Tak. Każda lekcja System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Techniki automatycznej instrumentacji
  2. Najlepsze praktyki instrumentacji ręcznej
  3. Propagacja kontekstu i baggage
  4. Atrybuty spanów, zdarzenia i status
← Powrót do System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)