System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) · レッスン

手動計装のベストプラクティス

可観測性データを細かく制御するために、手動計装をいつ、どのように適用するかを理解します。カスタム属性でトレースを拡張する方法も学びます。

レッスン 2/411 ステップ

「手動計装のベストプラクティス」はCoddyKit上の無料System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)レッスンです。これはレッスン2/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはSystem Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)コースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

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.

無料で開始

AI チューターと学ぶ System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry) — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース: 12
レッスン: 48

無料で学習を始めるコース全体を表示

よくある質問

「手動計装のベストプラクティス」レッスンは無料ですか？

はい。「手動計装のベストプラクティス」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)コースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)コースには全4レッスンが含まれています。

「手動計装のベストプラクティス」で何を学びますか？

可観測性データを細かく制御するために、手動計装をいつ、どのように適用するかを理解します。カスタム属性でトレースを拡張する方法も学びます。ブラウザで直接実行するハンズオンコードでSystem Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)を演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)を始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのSystem Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)は初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン2/4です。

「手動計装のベストプラクティス」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このSystem Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)レッスンでコードを書いて実行できますか？

はい。すべてのSystem Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)レッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← System Observability: Logging, Metrics & Tracing (ELK + OpenTelemetry)に戻る