/ /

OpenTelemetry による追跡

Overview

このガイドでは、 Rubyドライバーで OpenTelemetry トレースを使用する方法を学習します。 OpenTelemetry は、テレメトリデータの測定、生成、収集、エクスポートを行う標準化された方法を提供するオープンソースの可用性フレームワークです。

Rubyドライバーは、 MongoDB操作のパフォーマンスと動作を理解するために OpenTelemetry トレースをサポートしています。トレースを有効にすると、ドライバーはクエリ、更新、トランザクションなどの操作を表す範囲を作成します。これらの範囲には、 MongoDB のセマンティック規則に従う属性が含まれます。

必要な依存関係

OpenTelemetry トレースを使用するには、OpenTelemetry Ruby SDK とエクスポートツールをインストールする必要があります。これらをアプリケーションにインストールするには、次の gem を Gemfile に追加します。

gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'  # or your preferred exporter

トレースを有効にしても OpenTelemetry ライブラリがロードされていない場合、ドライバーは警告をログに記録し、トレースを自動的に無効にします。

OpenTelemetry トレースの有効化

OpenTelemetry トレースは、クライアントを作成するときに tracing オプションを指定するか、環境変数を設定することで有効にできます。

注意

クライアント構成または環境変数を使用してトレースを設定しない場合、トレースはデフォルトで無効になります。

クライアント構成でのトレース機能の有効化

クライアントの作成時にトレースを有効にするには、次の例に示すように、enabled を true に設定して tracing オプションを渡します。

client = Mongo::Client.new(['localhost:27017'], 
  database: 'my_database',
  tracing: {
    enabled: true
  }
)

環境変数を使用してトレースを有効にする

環境変数を使用してトレースを有効にするには、次の例に示すように、クライアントを作成する前に OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED 環境変数を設定します。

export OTEL_RUBY_INSTRUMENTATION_MONGODB_ENABLED=true

トレースを有効にするには、環境変数で次のいずれかの値を使用できます。

true
1
yes

変数を設定したら、次の例に示すようにクライアントを作成します。

client = Mongo::Client.new(['localhost:27017'], 
  database: 'my_database')

設定オプション

tracing オプションは次のパラメータを受け入れます。

Parameter	タイプ	説明
`:enabled`	ブール値	Enables or disables OpenTelemetry tracing. Default: `nil`
`:query_text_max_length`	整数	Specifies the maximum length of query text to include in span attributes. Set to `0` to exclude query text. The query text appears in the `db.query.text` attribute. Default: `nil`
`:tracer`	`OpenTelemetry::Trace::Tracer`	Specifies a custom OpenTelemetry tracer instance. Default: Uses the default tracer from the global tracer provider

次の例は、利用可能なすべてのトレースオプションを構成する方法を示しています。

client = Mongo::Client.new(['localhost:27017'],
  database: 'my_database',
  tracing: {
    enabled: true,
    query_text_max_length: 1024,
    tracer: my_custom_tracer
  }
)

操作トレース

Rubyドライバーは、高レベルの操作と低レベルのコマンドの両方に対して OpenTelemetry の範囲を作成します。次のセクションでは、作成された範囲と含まれる属性について説明します。

高レベルの操作

高レベルの操作は、コレクションとデータベースに対して直接呼び出すメソッドです。ドライバーは、次の操作の範囲を作成します。

操作タイプ	操作
コレクション操作	`find`、`insert_one`、`insert_many`、`update_one`、`update_many`、`delete_one`、`delete_many`、`find_one_and_update`、`find_one_and_delete`、`find_one_and_replace`、`replace_one`、`count_documents`、`estimated_document_count`、`distinct`、`aggregate`
インデックス操作	`create_index`, `create_indexes`, `drop_index`, `drop_all_indexes`, `list_indexes`
データベース操作	`list_collections`, `create_collection`, `drop_collection`, `list_databases`

ハイレベル操作のスパン名には {operation_name}.{collection_name} という形式が使用されます。例、find.users、insertOne.orders、aggregate.products など。

低レベルコマンド

低レベルコマンドは、ワイヤプロトコル経由でMongoDBサーバーに送信される実際のコマンドです。以下は、ドライバーが範囲を作成する低レベルコマンドの例をいくつか示します。

find
insert
update
delete
aggregate
create
drop

低レベルコマンドのスパン名は {command_name} という形式を使用します。例、find、insert、update など。

コマンド範囲は、対応する操作範囲の下にネストされます。

範囲属性

ドライバーはMongoDB のセマンティック規則に従い、各操作に関するコンテキストを提供する範囲属性を含めています。

すべての範囲には次の属性が含まれます。

db.system.name: 常にに設定します mongodb
db.namespace:データベース名
db.collection.name:コレクション名（該当する場合）
db.command.name: MongoDBコマンド名（コマンドは範囲のみ）
db.query.summary：クエリ構造の概要

ネットワーク属性

コマンド範囲には、次のネットワーク属性が含まれます。

server.address: MongoDBサーバーホスト
server.port: MongoDBサーバーポート
network.transport: などのトランスポートプロトコル tcp

接続属性

コマンド範囲には、次の接続属性が含まれます。

db.mongodb.server_connection_id: サーバーに割り当てられた接続ID
db.mongodb.driver_connection_id: ドライバーに割り当てられた接続ID

セッションとトランザクションの属性

セッションまたはトランザクションを使用する場合、範囲には次の属性が含まれます。

db.mongodb.lsid: 論理セッションID （セッションを使用する場合）
db.mongodb.txn_number: トランザクション番号（トランザクション内）
db.mongodb.cursor_id: カーソルID （カーソルを返す操作）

クエリ属性

query_text_max_length を 0 より大きい値で構成すると、範囲には次の属性が含まれます。

db.query.text: 指定された最大長まで切り捨てられた完全なクエリテキスト

エラー属性

操作が失敗すると、ドライバーは OpenTelemetry の例外記録メカニズムを使用して例外の詳細を記録し、範囲ステータスを ERROR に設定します。 MongoDB操作が失敗した場合、db.response.status_code 属性にはエラーコードが含まれます。

トランザクション追跡

ドライバーは、明示的なトランザクション内のすべての操作を含む特別なトランザクション範囲を作成します。次の例は、トランザクション追跡を示しています。

session = client.start_session
session.with_transaction do
  collection.insert_one({ name: 'Alice' }, session: session)
  collection.update_one(
    { name: 'Bob' }, 
    { '$set' => { age: 30 } }, 
    session: session
  )
end

上記の例では、次の構造のような範囲の階層が生成されます。

transaction
  └── insertOne.users
      └── insert (command)
  └── updateOne.users
      └── update (command)

注意

暗黙的なセッションではトランザクション範囲は作成されません。

Error Handling

操作が失敗すると、ドライバーは OpenTelemetry の例外記録メカニズムを使用して、範囲内に例外を記録します。範囲ステータスは ERROR に設定されます。

MongoDB操作が失敗した場合、db.response.status_code 属性にはエラーコードが含まれます。

エラーは発生しても、ドライバーはアプリケーションに対して例外を発生させることはありません。

パフォーマンスに関する考慮事項

OpenTelemetry トレースを使用する場合は、次のパフォーマンスへの影響を考慮してください。

トレースを有効にすると、ドライバーは範囲の作成と属性のコレクションに最小限のオーバーヘッドを発生させます。
クエリテキストキャプチャ（db.query.text）には追加のオーバーヘッドがあるため、本番環境では判断して使用する必要があります。 query_text_max_length を 0 に設定すると、クエリテキストの取得が無効になり、パフォーマンスが向上します。
トレースを無効にすると、機能は完全にバイパスされるため、パフォーマンスへの影響はありません。

例

次の例は、 MongoDBアプリケーションの OpenTelemetry トレースを設定する方法を示しています。

require 'mongo'
require 'opentelemetry/sdk'
# Configure OpenTelemetry
OpenTelemetry::SDK.configure do |c|
  c.service_name = 'my-app'
end
# Create MongoDB client with tracing enabled
client = Mongo::Client.new(['localhost:27017'],
  database: 'test',
  tracing: { 
    enabled: true,
    query_text_max_length: 1024 
  }
)
# Use the client normally - operations are traced
collection = client[:users]
collection.insert_one({ name: 'Alice', age: 30 })
collection.find({ age: { '$gte': 25 } }).to_a

詳細情報

Rubyで OpenTelemetry をトレースする方法の詳細については、「 OpenTelemetry Ruby SDK 」を参照してください。