2. OpenTelemetry 核心概念：Signal（Trace/Metric/Log）、Resource、Instrumentation Scope

在深入指标采集优化与数据库迁移任务调度之前，必须建立对 OpenTelemetry 数据模型的统一认知。OpenTelemetry 将可观测性数据抽象为三大核心 Signal（信号），并引入 Resource（资源） 和 Instrumentation Scope（检测范围） 两个元数据层，用于描述“谁产生的数据”以及“由哪个库产生的数据”。

2.1 三大 Signal：Trace、Metric、Log

Signal 是 OpenTelemetry 中可观测性数据的顶级分类。每个 Signal 都有独立的数据模型和语义，但在实际系统中三者通过 Context 传播 和 Resource 关联 实现关联分析。

2.2 Resource（资源）

Resource 描述产生可观测性数据的 实体，例如主机、容器、Kubernetes Pod、数据库实例或应用服务。Resource 是一组键值对（Attributes），会被附加到该实体产生的所有 Signal 上，实现跨 Signal 的关联查询。

常见的 Resource 属性包括：

• service.name — 服务名称，如 migration-scheduler
• service.instance.id — 服务实例唯一标识
• host.name — 主机名
• telemetry.sdk.language — SDK 语言，如 java
• deployment.environment — 部署环境，如 production

2.3 Instrumentation Scope（检测范围）

Instrumentation Scope 标识产生 Signal 的 检测库或检测模块。它通常对应一个具体的 instrumentation 包（如 io.opentelemetry.instrumentation.jdbc）或自定义检测代码。Scope 包含 name、version 和 schema_url 三个字段。

Scope 与 Resource 的区别：

2.4 数据模型层次关系

下图展示了 OpenTelemetry 数据模型的完整层次结构，以及 Signal、Resource、Scope 之间的包含关系：

2.5 数据库迁移场景中的 Signal 关联

在迁移任务调度中，三个 Signal 通过 Trace ID 和 Resource Attributes 实现关联。例如，一次“全量迁移”任务会产生如下数据：

• Trace：一个 Root Span（任务调度）包含多个 Child Span（连接源库、读取表结构、导出数据、导入目标库、校验）。
• Metric：在导出和导入阶段，每 10 秒记录一次 migration.rows.processed（Counter）和 migration.duration（Histogram），并附加 table_name、batch_id 等属性。
• Log：当校验不一致时，输出一条 Error 级别的 LogRecord，包含 trace_id、span_id、不一致行主键和期望值/实际值。

2.6 核心概念速查表

2.7 代码示例：在 Java 中创建 Resource 和 Scope

以下代码展示了如何在数据库迁移调度器中显式设置 Resource 和 Instrumentation Scope：

// 创建 Resource，标识当前服务
Resource resource = Resource.getDefault()
    .merge(Resource.create(Attributes.of(
        ResourceAttributes.SERVICE_NAME, "migration-scheduler",
        ResourceAttributes.SERVICE_VERSION, "2.1.0",
        ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "production",
        ResourceAttributes.HOST_NAME, InetAddress.getLocalHost().getHostName()
    )));

// 创建 OpenTelemetry 实例
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
    .setResource(resource)
    .build();

// 创建自定义 Instrumentation Scope
Meter meter = openTelemetry.getMeter("custom-migration-instrumentation", "1.0.0");
Tracer tracer = openTelemetry.getTracer("custom-migration-instrumentation", "1.0.0");
Logger logger = openTelemetry.getLogsBridge()
    .loggerBuilder("custom-migration-instrumentation")
    .setInstrumentationVersion("1.0.0")
    .build();