計装

OpenTelemetry Pythonの手動計装

計装とは、あなた自身がアプリにオブザーバビリティコードを追加する行為です。

アプリを計装する場合、あなたが使用する言語に対応したOpenTelemetry SDKを使用する必要があります。次に、SDKを使用してOpenTelemetryを初期化し、APIを使用してコードを計装します。これにより、アプリ本体だけでなく、計装が含まれるライブラリからもテレメトリーが出力されるようになります。

ライブラリを計装する場合、使用する言語に対応したOpenTelemetry APIパッケージのみをインストールしてます。ライブラリ自体はテレメトリーを出力しません。ライブラリの計装についての詳細は、ライブラリを参照してください。

OpenTelemetry APIとSDKについての詳細は、仕様を参照してください。

セットアップ

まず、APIとSDKパッケージがインストールされていることを確認します。

pip install opentelemetry-api
pip install opentelemetry-sdk

トレース

トレーサーの取得

トレースを開始するには、TracerProviderを初期化し、オプションでグローバルデフォルトとして設定する必要があります。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    BatchSpanProcessor,
    ConsoleSpanExporter,
)

provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)

# グローバルデフォルトのトレーサープロバイダーを設定する
trace.set_tracer_provider(provider)

# グローバルトレーサープロバイダーからトレーサーを作成する
tracer = trace.get_tracer("my.tracer.name")

スパンの作成

通常、スパンを作成するには、現在のスパンとして開始します。

def do_work():
    with tracer.start_as_current_span("span-name") as span:
        # 'span'が追跡する作業を行う
        print("doing some work...")
        # 'with'ブロックのスコープを抜けると、'span'は自動的に閉じられる

start_spanを使用して、現在のスパンとせずにスパンを作成することもできます。これは通常、並行処理や非同期処理を追跡するために使用します。

ネストされたスパンの作成

別の操作の一部として追跡したい個別のサブ操作がある場合、その関係を表すスパンを作成できます。

def do_work():
    with tracer.start_as_current_span("parent") as parent:
        # 'parent'が追跡する作業を行う
        print("doing some work...")
        # ネストされた作業を追跡するためのネストされたスパンを作成する
        with tracer.start_as_current_span("child") as child:
            # 'child'が追跡する作業を行う
            print("doing some nested work...")
            # ネストされたスパンはスコープを抜けると閉じられる

        # このスパンもスコープを抜けると閉じられる

トレースの可視化ツールでスパンを表示すると、childはparentの下にネストされたスパンとして追跡されます。

デコレーターによるスパンの作成

単一のスパンで関数全体の実行を追跡することはよくあります。そのような場合、コードを削減するためにデコレーターを使用できます。

@tracer.start_as_current_span("do_work")
def do_work():
    print("doing some work...")

デコレーターの使用は、do_work()内でスパンを作成し、do_work()の完了時にスパンを終了することと同等です。

デコレーターを使用するには、関数宣言のグローバルスコープでtracerインスタンスが利用可能である必要があります。

現在のスパンの取得

ある時点で現在のスパンにアクセスし、追加情報を付与したい場合があります。

from opentelemetry import trace

current_span = trace.get_current_span()
# 'current_span'に情報を付与する

スパンへの属性の追加

属性を使用すると、スパンにキーバリューのペアを付与でき、追跡中の現在の操作に関するより多くの情報を保持できます。

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.set_attribute("operation.value", 1)
current_span.set_attribute("operation.name", "Saying hello!")
current_span.set_attribute("operation.other-stuff", [1, 2, 3])

セマンティック属性の追加

セマンティック属性は、一般的な種類のデータに対するよく知られた命名規則として事前定義された属性です。セマンティック属性を使用すると、システム全体でこの種の情報を正規化できます。

Pythonでセマンティック属性を使用するには、セマンティック規約パッケージがインストールされていることを確認してください。

pip install opentelemetry-semantic-conventions

その後、コード内で使用できます。

from opentelemetry import trace
from opentelemetry.semconv.trace import SpanAttributes

// ...

current_span = trace.get_current_span()
current_span.set_attribute(SpanAttributes.HTTP_METHOD, "GET")
current_span.set_attribute(SpanAttributes.HTTP_URL, "https://opentelemetry.io/")

イベントの追加

イベントは、スパンのライフタイム中に「何かが起こった」ことを表す、人間が読めるメッセージです。プリミティブなログと考えることができます。

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.add_event("Gonna try it!")

# 処理を行う

current_span.add_event("Did it!")

リンクの追加

スパンは、別のスパンと因果関係を持つゼロ個以上のスパンリンクを持つように作成できます。リンクを作成するにはスパンコンテキストが必要です。

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("span-1"):
    # 'span-1'が追跡する処理を行う
    ctx = trace.get_current_span().get_span_context()
    link_from_span_1 = trace.Link(ctx)

with tracer.start_as_current_span("span-2", links=[link_from_span_1]):
    # 'span-2'が追跡する処理を行う
    # 'span-2'のリンクは'span-1'と因果関係がありますが、
    # 子スパンではありません
    pass

スパンステータスの設定

ステータスはスパンに設定でき、通常はスパンが正常に完了しなかったことを示すために使用されます。つまりErrorです。デフォルトでは、すべてのスパンはUnsetであり、これはスパンがエラーなく完了したことを意味します。 Okステータスは、デフォルトのUnset（つまり「エラーなし」）のままにするのではなく、スパンを明示的に成功としてマークする必要がある場合に予約されています。

ステータスは、スパンが終了する前であればいつでも設定できます。

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

current_span = trace.get_current_span()

try:
    # 失敗する可能性のある処理
except:
    current_span.set_status(Status(StatusCode.ERROR))

スパンでの例外の記録

例外が発生した場合に記録することは良いプラクティスです。スパンステータスの設定とあわせて行うことをお勧めします。

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

current_span = trace.get_current_span()

try:
    # 失敗する可能性のある処理

# コード内ではより具体的な例外をキャッチすることを検討してください
except Exception as ex:
    current_span.set_status(Status(StatusCode.ERROR))
    current_span.record_exception(ex)

デフォルトの伝搬フォーマットの変更

デフォルトでは、OpenTelemetry Pythonは以下の伝搬フォーマットを使用します。

W3C Trace Context
W3C Baggage

デフォルトを変更する必要がある場合は、環境変数またはコードで設定できます。

環境変数の使用

OTEL_PROPAGATORS環境変数にカンマ区切りのリストを設定できます。受け入れられる値は以下のとおりです。

"tracecontext": W3C Trace Context
"baggage": W3C Baggage
"b3": B3 Single
"b3multi": B3 Multi
"jaeger": Jaeger
"xray": AWS X-Ray（サードパーティ）
"ottrace": OT Trace（サードパーティ）
"none": 自動設定されるプロパゲーターなし

デフォルトの設定はOTEL_PROPAGATORS="tracecontext,baggage"と同等です。

SDK APIの使用

かわりに、コード内でフォーマットを変更することもできます。

たとえば、ZipkinのB3伝搬フォーマットを使用する必要がある場合は、B3パッケージをインストールします。

pip install opentelemetry-propagator-b3

そして、トレースの初期化コードでB3プロパゲーターを設定します。

from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.b3 import B3Format

set_global_textmap(B3Format())

環境変数はコードで設定されたものを上書きすることに注意してください。

参考資料

メトリクス

メトリクスの収集を開始するには、MeterProviderを初期化し、オプションでグローバルデフォルトとして設定する必要があります。

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import (
    ConsoleMetricExporter,
    PeriodicExportingMetricReader,
)

metric_reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
provider = MeterProvider(metric_readers=[metric_reader])

# グローバルデフォルトのメータープロバイダーを設定する
metrics.set_meter_provider(provider)

# グローバルメータープロバイダーからメーターを作成する
meter = metrics.get_meter("my.meter.name")

同期計装の作成と使用

計装は、アプリケーションの計測に使用されます。同期計装は、リクエストの処理や別のサービスの呼び出しなど、アプリケーションやビジネスの処理ロジックと連動して使用されます。

まず、計装を作成します。計装は通常、モジュールまたはクラスレベルで一度作成され、ビジネスロジックと連動して使用されます。この例では、完了した作業項目の数をカウントするためにCounter計装を使用します。

work_counter = meter.create_counter(
    "work.counter", unit="1", description="Counts the amount of work done"
)

Counterのadd操作を使用して、以下のコードでは作業項目のタイプを属性としてカウントを1つ増やします。

def do_work(work_item):
    # 実行中の作業をカウントする
    work_counter.add(1, {"work.type": work_item.work_type})
    print("doing some work...")

非同期計装の作成と使用

非同期計装は、オンデマンドで呼び出されるコールバック関数を登録する方法を提供します。これは、直接計装できない値を定期的に計測するのに便利です。非同期計装は、メトリクス収集中に呼び出されるゼロ個以上のコールバックとともに作成されます。各コールバックはSDKからのオプションを受け取り、その観測値を返します。

この例では、HTTPエンドポイントをスクレイピングして設定サーバーから提供される現在の設定バージョンを報告するために、非同期ゲージ計装を使用します。まず、観測値を作成するコールバックを記述します。

from typing import Iterable
from opentelemetry.metrics import CallbackOptions, Observation


def scrape_config_versions(options: CallbackOptions) -> Iterable[Observation]:
    r = requests.get(
        "http://configserver/version_metadata", timeout=options.timeout_millis / 10**3
    )
    for metadata in r.json():
        yield Observation(
            metadata["version_num"], {"config.name": metadata["version_num"]}
        )

OpenTelemetryはタイムアウトを含むオプションをコールバックに渡すことに注意してください。コールバックは無限にブロックしないよう、このタイムアウトを尊重する必要があります。最後に、コールバックとともに計装を作成して登録します。

meter.create_observable_gauge(
    "config.version",
    callbacks=[scrape_config_versions],
    description="The active config version for each configuration",
)

参考資料

ログ

ログAPIおよびSDKは現在開発中です。ログの収集を開始するには、LoggerProviderを初期化し、オプションでグローバルデフォルトとして設定する必要があります。その後、Pythonの組み込みロギングモジュールを使用して、OpenTelemetryが処理できるログレコードを作成します。

import logging
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, ConsoleLogRecordExporter # 1.39.0より前のバージョンではConsoleLogExporter
from opentelemetry._logs import set_logger_provider

provider = LoggerProvider()
processor = BatchLogRecordProcessor(ConsoleLogRecordExporter())
provider.add_log_record_processor(processor)
# グローバルデフォルトのロガープロバイダーを設定する
set_logger_provider(provider)

handler = LoggingHandler(level=logging.INFO, logger_provider=provider)
logging.basicConfig(handlers=[handler], level=logging.INFO)

logging.getLogger(__name__).info("This is an OpenTelemetry log record!")

参考資料

セマンティック規約の安定性

Python の計装ライブラリは、環境変数 OTEL_SEMCONV_STABILITY_OPT_IN をサポートしています。この変数を使用すると、計装が安定版のセマンティック規約を出力するか、以前の実験的な規約を出力するか、あるいは移行中に両方を出力するかを制御できます。

HTTP とデータベースのサポートは、OpenTelemetry Python 1.44.0 / 0.65b0 から利用可能です。この変数はカンマ区切りの値のリストを受け付けます。

http: 新しい安定版の HTTP およびネットワーキング規約を出力し、以前計装が出力していた古い実験的な HTTP およびネットワーキング規約の出力を停止します。
http/dup: 古い規約と安定版の HTTP およびネットワーキング規約の両方を出力し、シームレスな移行を可能にします。
database: 新しい安定版のデータベース規約を出力し、以前計装が出力していた古い実験的なデータベース規約の出力を停止します。
database/dup: 古い規約と安定版のデータベース規約の両方を出力し、シームレスな移行を可能にします。
gen_ai_latest_experimental: 古い GenAI 規約のかわりに、計装がサポートする最新の実験的な GenAI 規約を出力します。

変数が設定されていない場合、計装はデフォルトで以前の実験的な規約を出力し続けます。値とその /dup バリアントの両方が存在する場合は、/dup バリアントが優先されます。

たとえば次のようにします。

export OTEL_SEMCONV_STABILITY_OPT_IN=http/dup,database

パッケージ固有の詳細については、opentelemetry-python-contrib Read the Docs で個々の計装のドキュメントを参照してください。

次のステップ

テレメトリーデータのエクスポートを行うために、適切なエクスポーターを設定することも必要です。

フィードバック

このページは役に立ちましたか?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

最終更新 September 30, 2026: [ja] update translation of content/en/docs/languages/python/instrumentation.md (#11900) (2fd4f4e9)