/ /

使用 OpenTelemetry 进行跟踪

Overview

在本指南中，您将学习；了解如何将 OpenTelemetry 跟踪与Ruby驾驶员结合使用。 OpenTelemetry 是一个开源可观察性框架，它提供了一种标准化方法来检测、生成、收集和导出遥测数据。

Ruby驾驶员支持 OpenTelemetry 跟踪，以帮助您了解MongoDB操作的性能和行为。启用跟踪后，驾驶员会创建表示查询、更新和事务等操作的 span。这些跨度包括遵循MongoDB语义约定的属性。

所需的依赖项

要使用 OpenTelemetry 跟踪，必须安装 OpenTelemetry Ruby SDK 和导出器。要在应用程序中安装这些工具，请将以下 gem 添加到您的 Gemfile 中：

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

如果启用跟踪但未加载 OpenTelemetry 库，驾驶员会记录警告并自动禁用跟踪。

启用 OpenTelemetry 跟踪

您可以通过在创建客户端时指定 tracing 选项或设置环境变量来启用OpenTelemetry 跟踪。

注意

如果未在客户端配置中或使用环境变量设立跟踪，则默认下禁用跟踪。

在客户端配置中启用跟踪

要在创建客户端时启用跟踪，请传递 tracing 选项，并将 enabled设立为 true，如以下示例所示：

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 span。以下部分描述了创建的 span 和包含的属性。

高级操作

高级操作是直接对集合和数据库调用的方法。驾驶员会为以下操作创建 span：

操作类型	操作
集合操作	`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`

高级操作的 Span 名称使用 {operation_name}.{collection_name} 格式。示例，find.users、insertOne.orders 或 aggregate.products。

低级命令

低级命令是通过传输协议发送到MongoDB服务器的实际命令。下面列出了驾驶员为其创建 span 的低级命令的一些示例：

find
insert
update
delete
aggregate
create
drop

低级命令的 Span 名称使用 {command_name} 格式。示例，find、insert 或 update。

命令范围嵌套在相应的操作范围下。

Span 属性

该驾驶员遵循MongoDB语义约定，并包含提供每个操作上下文的 span 属性。

所有 span 都包含以下属性：

db.system.name：始终设立为 mongodb
db.namespace：数据库名称
db.collection.name：集合名称（如果适用）
db.command.name： MongoDB命令名称（仅限命令 span）
db.query.summary：查询结构的高级摘要

网络属性

命令范围包括以下网络属性：

server.address： MongoDB 服务器托管
server.port： MongoDB服务器端口
network.transport：传输协议，例如 tcp

连接属性

命令范围包括以下连接属性：

db.mongodb.server_connection_id：服务器分配的连接ID
db.mongodb.driver_connection_id：驱动程序分配的连接ID

会话和事务属性

使用会话或事务时，span 包括以下属性：

db.mongodb.lsid：逻辑会话ID （使用会话时）
db.mongodb.txn_number：事务编号（处于ACID 事务中时）
db.mongodb.cursor_id：游标ID （适用于返回游标的操作）

查询属性

当您将 query_text_max_length 配置为大于 0 的值时，span 将包含以下属性：

db.query.text：完整的查询文本，已截断为指定的最大长度

错误属性

当操作失败时，驾驶员会使用 OpenTelemetry 的异常记录机制记录异常详细信息，并将 span 状态设置为 ERROR。对于MongoDB操作失败，db.response.status_code 属性包含错误代码。

交易跟踪

驾驶员创建一个特殊的ACID 事务范围，其中包含显式ACID 事务中的所有操作。以下示例演示了ACID 事务跟踪：

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

前面的示例生成了一个类似于以下结构的 span 层次结构：

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

注意

隐式会话不会创建ACID 事务跨度。

Error Handling

当操作失败时，驾驶员会使用 OpenTelemetry 的异常记录机制在 span 中记录异常。然后，将跨度状态设立为 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