SELECT * FROM projects WHERE id = " />Span 类型Span kind 必须是以下值之一:
server
用于服务器操作,例如 HTTP 服务器处理程序。client
用于客户端操作,例如 HTTP 客户端请求。producer
对于消息生产者,例如 Kafka producer。consumer
一般用于消息消费者和异步处理,例如 Kafka consumer。internal
用于内部操作。Status code(状态码) 状态码表示操作成功或失败。必须是以下值之一:
ok
- 成功。error
- 失败。unset
- 允许后端分配状态的默认值。Attributes(属性) 要记录上下文信息,您可以用带有特定于操作的信息的属性对 span 进行注释。例如,HTTP 端点可能具有 http.method = GET
与 http.route = /projects/:id
。
您可以随意命名属性,但对于常见操作,您应该使用 semantic attributes 约定。它定义了一个公共属性键列表,其中包含它们的含义和可能的值。
Events(事件) 您还可以用具有开始时间和任意数量属性的事件注释 span 。事件和 span 的主要区别在于事件没有结束时间(因此没有持续时间)。
事件通常表示异常、错误、日志和消息(例如在 RPC 中),但是您也可以创建自定义事件。
Context(上下文) 当 Span context 通过不同的组件和服务传播时,它携带有关该 span 的信息。
Trace/span context 是一个请求范围的数据,例如:
Trace ID . 表示整个 trace 或 query 的全局唯一标识符。trace 中的所有 span 都具有相同的 trace ID。
Span ID . trace 中特定 span 的唯一标识符。trace 中的每个 span 都有不同的 span ID。
Trace flags . 指示 trace 的各种属性的 flag,例如是否对其进行了采样。采样是指确定应记录哪些 span 并将其报告给可观测性后端的过程。
Trace State . 一个可选字段,包含与 trace 相关的其他供应商或应用程序特定数据。
Span context 对于保持分布式系统中 span 的连续性和相关性非常重要。它允许不同的服务和组件将其 span 与正确的跟踪相关联,并提供对请求或事务流的端到端可见性。
Span context 通常使用服务之间通信协议的标头或元数据进行传播,类似于 baggage 数据的传播方式。这确保了当服务接收到请求时,它可以提取 span context,并将传入的 span 与正确的 trace 相关联。
您可以使用上下文中的数据进行 span 相关性或采样,例如,您可以使用 trace id 来知道哪些 span 属于哪些 trace。
Context propagation(上下文传播) 上下文传播确保相关的上下文数据,如 trace ID、span ID 和其他元数据,在应用程序的不同服务和组件之间一致地传播。
OpenTemetry 在进程内的函数之间传播上下文(进程内传播),甚至从一个服务传播到另一个服务(分布式传播)。
进程内传播可以是隐式的,也可以是显式的,这取决于所使用的编程语言。隐式传播通过将活动上下文存储在线程局部变量(Java, Python, Ruby, NodeJS)中自动完成。显式传播需要显式地将活动上下文作为参数从一个函数传递到另一个函数(Go)。
对于分布式上下文传播,OpenTelemetry 支持几种协议,这些协议定义了如何序列化和传递上下文数据:
W3C trace context 在 traceparent
header 中, 例如, traceparent=00-84b54e9330faae5350f0dd8673c98146-279fa73bc935cc05-01
。https://www.w3.org/TR/trace-context/ B3 Zipkin 在以 x-b3-
开始的 header 中, 例如, X-B3-TraceId
。https://github.com/openzipkin/b3-propagation W3C trace context 是默认启用的推荐传播器。
Baggage(行李) Baggage 的工作原理类似于 span context,允许您将自定义 key:value 对(属性)从一个服务传播到另一个服务。在 gRPC 世界中,有一个类似的概念叫做 gRPC metadata。
https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md Baggage 允许您将键值对与请求或事务关联起来。这些键值对表示可能与请求或事务处理相关的上下文信息,例如 user ID、session ID 或其他特定于应用程序的元数据。
Baggage 有助于维护和关联跨分布式系统的上下文信息,从而实现对应用程序行为的更好的可观测性和分析。它提供了一种标准化的方式来在整个系统中传递相关数据,而不依赖于特别的机制或手动检测。
什么时候优先去 Instrumentation Instrumentation 官方详细文档
https://opentelemetry.io/docs/instrumentation/ 您不需要记录每个操作来充分利用跟踪。这可能会花费很多时间,而且通常是不必要的。优先考虑以下操作:
Network 操作, 例如,HTTP 请求或 RPC 调用。 Filesystem 操作, 例如,读/写文件。 Database 查询,它结合了网络与文件系统操作。 Errors and logs,例如,使用结构化日志。 OpenTelemetry Metrics(指标) OpenTelemetry Metrics 是一个关于如何收集、聚合和发送指标到 OpenTelemetry APM 工具(如 Uptrace 或 Prometheus )的标准。
在定义新标准的同时,OpenTelemetry 还致力于与现有的指标工具协议(如 Prometheus 和 Statsd)一起工作。此外,OpenTelemetry Collector 甚至支持更多的协议,如 AWS Metrics、InfluxDB、Chrony 等。
OpenTelemetry 还允许您通过示例关联指标和跟踪,这些示例应该向您展示系统状态的更广泛的图像。
什么是指标? 指标是表示系统运行状况和性能的数值数据点,例如 CPU 利用率、网络流量和数据库连接。
您可以使用指标来度量、监视和比较性能,例如,您可以度量服务器响应时间、内存利用率、错误率等等。
Instruments instrument 是一种特定类型的指标(例如,counter, gauge, histogram),用于收集关于应用程序行为的特定方面的数据。
您通过创建具有以下功能的 instrument 来捕获测量结果:
唯一的名称,例如 http.server.duration
。 一种 instrument 类型,例如 Histogram
。 一个可选的指标单位,例如 milliseconds
或 bytes
。 可选描述。 Timeseries(时间序列) 一个 instrument 可以生成多个时间序列。时间序列是一个具有唯一属性集的指标,例如,对于相同的指标名称,每个主机都有一个单独的时间序列。
Additive(可加) instruments Additive 或 summable instruments 产生的时间序列,当加在一起时,产生另一个有意义和准确的时间序列。测量 non-decreasing 数的 Additive instruments 也称为 monotonic(单调的)。
例如,http.server.requests
是一个 additive 时间序列,因为您可以将来自不同主机的请求数相加,以获得请求总数。
但是,system.memory.utilization
(百分比) 不是相加的,因为来自不同主机的内存利用率之和没有意义(90% + 90% = 180%
)。
Synchronous(同步) instruments Synchronous instruments 与它们正在测量的操作一起被调用。 例如,为了测量请求的数量,只要有新的请求,就可以调用 counter.Add(ctx, 1)
。 同步测量可以具有关联的 trace context
。
对于 synchronous instruments,additive 和 grouping instruments 之间的区别在于 additive instruments 产生 summable 时间序列,grouping instruments 产生 histogram。
Instrument Properties Aggregation Example Counter 单调的 sum -> delta 请求数,请求大小 UpDownCounter 可加的 last value -> sum 连接数 Histogram 可分组的 histogram 请求持续时间、请求大小
Asynchronous(异步) instruments Asynchronous instruments 定期调用回调函数来收集测量值。 例如,您可以使用观察器定期测量内存或 CPU 的使用情况。 Asynchronous 测量不能具有关联的 trace context。
在 UpDownCounterObserver
(additive) 和 GaugeObserver
(grouping)之间进行选择时, 对于 summable 时间序列,请选择 UpDownCounterObserver
,否则,请选择 GaugeObserver
。 例如,要测量 system.memory.usage
(bytes),应使用 UpDownCounterObserver
。 但要测量 system.memory.utilization
(百分比),您应该使用 GaugeObserver
。
Instrument Name Properties Aggregation Example CounterObserver 单调的 sum -> delta CPU time UpDownCounterObserver 可加的 last value -> sum Memory usage (bytes) GaugeObserver 可分组的 last value -> none/avg Memory utilization (%)
选择 instruments 如果您需要直方图、热图或百分位数,请使用 Histogram
。 如果您想通过记录增量值来计数:如果该值是 monotonic 的,请使用 Counter
。 否则,使用 UpDownCounter
。 如果你想通过记录一个绝对值来测量某个东西:如果该值是 additive/summable 的:如果该值是 monotonic 的,请使用 CounterObserver
。 否则,请使用 UpDownCounterObserver
。 如果该值不 additive/summable,请使用 GaugeObserver
。 Counter synchronous
monotonic
Counter
是一种同步 instrument,用于测量相加的非递减值,例如:
processed requests errors received bytes disk reads Counters 用于测量一个事件的发生次数或一个值随时间的累积。它们只能随着时间的推移而增加。
对于 Counter
时间序列,后端通常计算增量并显示速率值,例如,per_min(http.server.requests)
返回每分钟处理的请求数。
CounterObserver asynchronous
monotonic
CounterObserver 是 Counter
instrument 的异步版本。
UpDownCounter synchronous
additive
UpDownCounter
是一种同步 instrument,用于测量可随时间增加或减少的附加值,例如:
active requests open connections memory in use (megabytes) 对于加法非递减(non-decreasing
)值,应使用 Counter 或 CounterObserver。
对于 UpDownCounter
时间序列,后端通常显示最后一个值,但不同的时间序列可以加在一起, 例如,go.sql.connections_open
返回打开的连接总数,go.sql.connections_open{service.name = myservice}
返回一个服务的打开连接数。
UpDownCounterObserver asynchronous
additive
UpDownCounterOserver
是 UpDownCounter instrument 的异步版本。
Histogram synchronous
grouping
直方图是一种同步 instrument,它根据记录的值生成直方图,例如:
request latency request size 直方图用于测量值随时间的分布。对于直方图时间序列,后端通常显示百分位数、热图和直方图。
GaugeObserver asynchronous
grouping
GaugeObserver
是一种异步 instrument
,用于测量 sum
不能产生有意义或正确结果的非相加值,例如:
error rate memory utilization cache hit rate 对于 GaugeObserver
时间序列,后端通常显示最后一个值,不允许将不同的时间序列相加。
Metrics 示例 邮件数量 要测量发送的电子邮件数量,您可以创建 Counter instrument,并在发送电子邮件时递增:
import "go.opentelemetry.io/otel/metric"var emailCounter = meter.NewInt64Counter("some.prefix.emails",metric.WithDescription("Number of sent emails"),)emailCounter.Add(ctx, 1)
稍后,您可以添加更多属性来收集详细的统计信息,例如:
kind = welcome
和 kind = reset_password
可以测量不同的电子邮件。state = sent
和 state = bounced
以衡量退回的电子邮件。操作延迟 要测量操作的延迟,您可以创建 Histogram instrument 并与操作同步更新:
import "go.opentelemetry.io/otel/metric"var opHistogram = meter.NewInt64Histogram("some.prefix.duration",metric.WithDescription("Duration of some operation"),)t1 := time.Now()op(ctx)dur := time.Since(t1)opHistogram.Record(ctx, dur.Microseconds())
缓存命中率 要测量缓存命中率,可以创建一个 CounterObserver 并观察缓存统计信息:
import "go.opentelemetry.io/otel/metric"var counter metric.Int64CounterObserver// Arbitrary key/value labels.hits := []attribute.KeyValue{attribute.String("type", "hits")}misses := []attribute.KeyValue{attribute.String("type", "misses")}errors := []attribute.KeyValue{attribute.String("type", "errors")}batchObserver := meter.NewBatchObserver(func(ctx context.Context, result metric.BatchObserverResult) {stats := cache.Stats()result.Observe(hits, counter.Observation(int64(stats.Hits)))result.Observe(misses, counter.Observation(int64(stats.Misses)))result.Observe(errors, counter.Observation(int64(stats.Errors)))})counter = batchObserver.NewInt64CounterObserver("some.prefix.cache_operations")
出错率 要直接测量错误率,您可以创建一个 GaugeObserver 并观察该值,而不必担心它是如何计算的:
import "go.opentelemetry.io/otel/metric"_ = meter.NewFloat64GaugeObserver("some.prefix.error_rate",func(ctx context.Context, result metric.Float64ObserverResult) {result.Observe(rand.Float64())},metric.WithDescription("Error rate as reported by some other system"),)
OpenTelemetry Logs(日志) OpenTelemetry Logs 允许以一种能够与其他可观察信号进行关联和更好集成的方式记录和收集日志。
日志对于理解应用程序行为、诊断问题和监视系统运行状况至关重要。 分布式跟踪和指标提供了对系统性能的有价值的见解,而日志提供了关于特定事件、错误和应用程序行为的详细上下文和信息。
概述 虽然 OpenTelemetry 主要关注于收集指标和跟踪,但它也通过其日志 API 支持日志收集。OpenTelemetry 支持现有的日志解决方案,并确保它可以与现有的日志库和日志收集工具一起很好地工作。
OpenTelemetry 提供了一个日志 API,允许您检测应用程序并生成结构化日志。 OpenTelemetry Logging API 旨在与其他遥测数据(如指标和跟踪)一起工作,以提供统一的可观测性解决方案。
OpenTelemetry 强调结构化的日志,允许您通过属性或元数据向日志条目附加额外的上下文信息。 这允许您包含相关的详细信息,例如 timestamps, request IDs, user IDs, correlation IDs 和其他有助于日志分析和故障排除的自定义上下文。
不同类型的日志 OpenTelemetry 支持从应用程序或系统中的各种源捕获日志。根据日志的生成和收集方式,日志可以分为 3 类。
系统和基础设施日志 系统日志提供有关系统操作、性能和安全性的宝贵信息。系统日志通常由系统内的各种组件生成,包括操作系统、应用程序、网络设备和服务器。
系统日志是在主机级别编写的,具有无法轻易更改的预定义格式和内容。系统日志不包括有关跟踪上下文的信息。
Legacy first-party 日志 First-party 日志由内部应用程序生成,记录特定的应用程序事件、错误和用户活动。这些日志对于应用程序调试和故障排除非常有用。
通常,开发人员可以修改这些应用程序,以更改日志的编写方式和包含的信息。例如,为了将日志与跟踪关联起来,开发人员可以手动将跟踪上下文添加到每个日志语句中,也可以使用日志库的插件自动添加。
例如,要传播上下文并将日志记录与 span 相关联,可以在日志消息中使用以下属性:
trace_id
用于 TraceId, 十六进制编码。span_id
用于 SpanId, 十六进制编码。trace_flags
用于 trace flags, 根据 W3C traceflags 格式进行格式化。例如:
request failed trace_id=958180131ddde684c1dbda1aeacf51d3 span_id=0cf859e4f7510204
New first-party 日志 启动新项目时,您可以遵循 OpenTelemetry 的建议和最佳实践, 了解如何使用自动检测发出日志,或将日志库配置为使用 OpenTelemetry log 附加程序。
OpenTelemetry 的日志 API 允许开发人员对其应用程序进行 instrument, 以生成结构化日志,这些日志可以由日志后台或日志管理系统收集和处理。 日志 API 提供了一种将附加上下文信息附加到日志条目(如标签、属性或元数据)的方法。
使用 Logger API 记录不同严重性级别的事件或消息,如 debug、info、warn、error 等。 您还可以将其他属性或上下文附加到日志条目以提供更多信息。
OpenTelemetry 还提供了一种标准化的方法,用于在分布式系统中传播日志中的上下文。 这确保了相关的执行上下文被一致地捕获和保存,即使日志是由系统的不同组件生成的。
OpenTelemetry Logs 数据模型允许将 TraceId
和 SpanId
直接包含在 LogRecords
中。
OpenTelemetry 收集器 OpenTelemetry Collector 是一个灵活且可扩展的代理,用于收集、处理和导出遥测数据。 它简化了从多个源接收和管理遥测数据的任务,并能够将数据导出到多个后端或可观测性系统。
OpenTelemetry Collector 支持多个日志源,包括应用程序日志、日志文件、日志库和第三方日志系统。 它提供了与流行的日志框架和库的集成,实现了日志数据的无缝接收。
收集器提供了转换和丰富日志数据的功能。 您可以修改日志属性、添加元数据或使用其他上下文信息丰富日志,以增强其价值,并使其对分析和故障排除更有意义。
收集和处理后,OpenTelemetry Collector 可以将日志数据导出到各种日志后端或系统。 它支持将日志导出到流行的日志记录平台、存储系统或日志管理工具,以进行长期存储、分析和可视化。
OpenTelemetry 后端 一旦日志数据导出到日志后端,您就可以使用平台的功能处理和分析日志。这可以包括过滤、搜索、聚合和可视化日志,以深入了解应用程序的行为并解决问题。
OpenTelemetry Sampling(采样) OpenTelemetry 采样通过减少创建(采样)span 的数量,降低了跟踪的成本和冗长程度。就性能而言,采样可以节省收集、处理和导出 span 所需的 CPU 周期和内存。
什么是采样? 在分布式追踪中使用采样来控制收集并发送到跟踪后端的数据量。它有助于平衡数据量和跟踪精度之间的权衡。
在分布式跟踪中,请求在流经系统时生成 span。span 表示在处理该请求期间发生的单个操作或事件。 在一个复杂的系统中,这些 span 可能会变得非常多,并且将它们全部发送到跟踪后端可能会导致大量的开销和存储成本。
抽样涉及到决定哪些时间段要记录,哪些时间段要丢弃。
采样:何时何地 采样可能发生在 span 处理的不同阶段:
创建 trace 时 - 头部采样; 当后端接收到 trace 时 - 速率限制采样; 当完整的 trace 可用时 - 基于尾部的采样; 抽样策略的选择取决于几个因素,包括期望的可观测性水平、可用资源和系统的特定用例。
概率抽样 抽样提供了一种抽样概率,使得仅使用部分抽样 span 就能对所有 span 进行准确的统计计数。 例如,如果采样概率为 50%,采样的 span 数为 10,则调整后的(总) span 数为 10 / 50% = 20
。
Name Side Adjusted count Accuracy 基于头部的采样 Client-side Yes 100% 速率限制采样 Server-side Yes <90% 基于尾部采样 Server-side Yes <90%
基于头部的采样 基于头部的抽样尽可能早地做出抽样决策,并使用 context 将其传播给其他参与者。 这允许通过不收集任何用于删除 span (操作)的遥测数据来节省 CPU 和内存资源。
基于头部的采样是最简单、最准确、最可靠的采样方法,与所有其他方法相比,您应该更喜欢这种方法。
基于头的采样的一个缺点是,不能对有错误的 span 进行采样,因为创建 span 时该信息不可用。 为了解决这个问题,可以使用基于尾部的采样。
基于头部的采样也不考虑流量峰值,并且可能收集比期望的更多的数据。这就是 rate-limiting 采样变得方便的地方。
OpenTelemetry 中基于头的采样 OpenTelemetry 有 2 个 span 属性负责客户端采样:
IsRecording
- 当为 false
时,span 将丢弃属性、事件、链接等。Sampled
- 当为 false
时,OpenTelemetry 删除 span。您应该检查 IsRecording
属性,以避免收集昂贵的遥测数据。
if span.IsRecording() {// collect expensive data}
Sampler 是一个接受将要创建的 root span 的函数。该函数返回一个采样决策,该决策必须是:
Drop - trace 被丢弃。IsRecording = false
, Sampled = false
。 RecordOnly - 记录 trace,但不采样。IsRecording = true
, Sampled = false
。 RecordAndSample - 记录并采样 trace。IsRecording = true
, Sampled = true
。 默认情况下,OpenTelemetry 对所有跟踪进行采样,但您可以将其配置为对部分跟踪进行采样。 在这种情况下,后端使用概率抽样来调整 span 的数量。
OpenTelemetry 采样器 AlwaysOn sampler 对每个 trace 进行采样,例如,将为每个请求启动并导出一个新的 trace。
AlwaysOff sampler 不采样 trace,换句话说,删除所有 trace。您可以使用此采样器执行负载测试或暂时禁用 trace。
TraceIDRatioBased sampler 使用 trace id 对跟踪的一小部分进行采样,例如,20% 的跟踪。
Parent-based sampler 是一种复合采样器,它根据 span 的父元素表现出不同的行为。当您开始一个新的 trace 时,采样器将决定是否对其进行采样,并将该决策向下传播到其他服务。
速率限制采样 速率限制采样发生在服务器端,并确保您不会超过某些限制,例如,它允许每秒采样 10 个或更少的跟踪。
限速采样支持调整计数,但精度较低。为了获得更好的结果并提高性能,您应该将限速采样与更有效和准确的基于头部的采样一起使用。
大多数后端在必要时自动应用限速采样。
基于尾部采样 在基于头部的采样的抽样中,抽样决策是预先做出的,通常是随机的。 基于头部的采样不能对失败或异常长时间的操作进行采样,因为这些信息只能在跟踪结束时获得。
使用基于尾部的采样,我们延迟采样决策,直到跟踪的所有 span 可用,这使得基于来自跟踪的所有数据的更好的采样决策。例如,我们可以对失败或异常长的跟踪进行采样。
大多数 OpenTelemetry 后端在必要时自动应用基于尾部的采样,但是你也可以使用 OpenTelemetry Collector 和 tailsamplingprocessor 来根据你的需要配置采样。
基于概率的采样 基于概率的采样根据配置的概率或采样率随机选择要记录的跟踪的子集。 例如,您可以设置采样率为 10%,这意味着只记录 10% 的迹线,其余的迹线被丢弃。
当您希望减少跟踪数据的数量,同时仍然保持系统行为的代表性样本时,基于概率的采样非常有用。 它有助于在开销和所需的可观测性级别之间取得平衡。
以下是如何在 OpenTelemetry Go 中配置基于概率的采样器,基于 Uptrace。
import "go.opentelemetry.io/contrib/samplers/probability/consistent"sampler := consistent.ParentProbabilityBased(consistent.ProbabilityBased(0.5), // sample 50% of traces)uptrace.ConfigureOpentelemetry(uptrace.WithTraceSampler(sampler),// Other options)
OpenTelemetry Collector(收集器) OpenTelemetry Collector 是一个高性能、可扩展和可靠的数据收集管道,用于可观察性数据。它从各种来源接收遥测数据,执行处理和转换为通用格式,然后将数据导出到各种后端进行存储和分析。
Otel Collector 支持多种数据格式、协议和平台,使其成为可观察性需求的灵活、可扩展的解决方案。
OpenTelemetry Collector 是如何工作的? OpenTelemetry Collector 是应用程序和分布式跟踪工具(如 SigNoz/Jaeger)之间与供应商无关的代理/中间人。
OpenTelemetry Collector 的工作原理是接收来自各种来源的遥测数据, 对数据进行处理和规范化,然后将其导出到各种后端进行存储和分析。
Otel Collector 提供强大的数据处理能力,允许您执行聚合,过滤,采样和丰富的遥测数据。 在将数据发送到后端系统之前,您可以转换和重塑数据以满足特定的监视和分析需求。
Otel Collector 是用 Go 语言编写的,使用 Apache 2.0 license ,允许您更改源代码并安装自定义扩展。这是以运行和维护您自己的 OpenTelemetry Collector 实例为代价的。
何时使用 OpenTelemetry Collector" />Otelcol 与 Otelcol-Contrib OpenTelemetry Collector 在 GitHub 上有 2 个存储库:
opentelemetry-collector 是只包含最关键组件的核心。它以 otelcol
二进制文件的形式分发。https://github.com/open-telemetry/opentelemetry-collector opentelemetry-collector-contrib 包含核心和所有额外的可用组件,例如,Redis 和 PostgreSQL 接收器。它以 otelcol-contrib
二进制文件的形式分发。https://github.com/open-telemetry/opentelemetry-collector-contrib 您应该始终安装和使用 otelcol-contrib
,因为它和核心一样稳定,并且支持更多的特性。
安装 OpenTelemetry Collector 为 Linux、MacOS 和 Windows 分发预编译的二进制文件。
Linux 要安装 otelcol-contrib
binary 和相关的 systemd 服务,运行以下命令将 0.82.0
替换为所需的版本,并将 amd64
替换为所需的架构:
Debian
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.82.0/otelcol-contrib_0.82.0_linux_amd64.debsudo dpkg -i otelcol-contrib_0.82.0_linux_amd64.deb
RPM
wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.82.0/otelcol_0.82.0_linux_amd64.rpmsudo rpm -ivh otelcol_0.82.0_linux_amd64.rpm
您可以使用以下命令检查已安装服务的状态:
sudo systemctl status otelcol-contrib
使用以下命令检查日志:
sudo journalctl -u otelcol-contrib -f
您可以在 /etc/otelcol-contrib/config.yaml
中编辑配置。并重新启动 OpenTelemetry Collector:
sudo systemctl restart otelcol-contrib
从源代码编译 你也可以在本地编译 OpenTelemetry Collector:
git clone https://github.com/open-telemetry/opentelemetry-collector-contrib.gitcd opentelemetry-collector-contribmake install-toolsmake otelcontribcol./bin/otelcontribcol_linux_amd64 --config ./examples/local/otel-config.yaml
配置 OpenTelemetry Collector 是高度可配置的,允许您自定义其行为并将其集成到可观测性堆栈中。它提供了用于指定输入、处理器和导出器的配置选项,使您能够根据自己的特定需求定制代理。
默认情况下,你可以在 /etc/otelcol-contrib/config.yaml
中找到配置文件。例如(Uptrace):
# receivers configure how data gets into the Collector.receivers:otlp:protocols:grpc:http:# processors specify what happens with the received data.processors:resourcedetection:detectors: [env, system]cumulativetodelta:batch:send_batch_size: 10000timeout: 10s# exporters configure how to send processed data to one or more backends.exporters:otlp/uptrace:endpoint: otlp.uptrace.dev:4317headers:uptrace-dsn: 'https://@uptrace.dev/'# service.pipelines pull the configured receivers, processors, and exporters together into# pipelines that process data.## receivers, processors, and exporters that are not used in pipelines are silently ignored.service:pipelines:traces:receivers: [otlp]processors: [batch]exporters: [otlp/uptrace]metrics:receivers: [otlp]processors: [cumulativetodelta, batch, resourcedetection]exporters: [otlp/uptrace]logs:receivers: [otlp]processors: [batch]exporters: [otlp/uptrace]
您可以通过官方文档了解更多关于 Otel Collector 的信息。
https://opentelemetry.io/docs/collector/configuration/ 故障排除 如果 otelcol 没有像预期的那样工作,您可以检查日志输出是否存在潜在问题。日志记录的详细程度默认为 INFO
,但您可以使用配置文件更改它:
service:telemetry:logs:level: 'debug'
查看潜在问题的日志。
sudo journalctl -u otelcol-contrib -f
您还可以启用 metrics 来监视 OpenTelemetry Collector:
receivers:prometheus/otelcol:config:scrape_configs:- job_name: 'otelcol'scrape_interval: 10sstatic_configs:- targets: ['0.0.0.0:8888']service:telemetry:metrics:address: ':8888'pipelines:metrics/hostmetrics:receivers: [prometheus/otelcol]processors: [cumulativetodelta, batch, resourcedetection]exporters: [otlp/uptrace]
扩展 Extensions 为 OpenTelemetry Collector 提供了额外的功能,并且不需要直接访问遥测数据, 例如,健康检查扩展响应健康检查请求。
extensions:# Health Check extension responds to health check requestshealth_check:# PProf extension allows fetching Collector's performance profilepprof:# zPages extension enables in-process diagnosticszpages:# Memory Ballast extension configures memory ballast for the processmemory_ballast:size_mib: 512
资源检测 为了检测来自主机的资源信息,Otel Collector 自带 resourcedetection processor。
https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor Resource Detection Processor 自动检测和标记有关数据生成环境的元数据。 这种元数据称为 "resources",为遥测数据提供上下文,可以包括主机、服务、容器和云提供商等信息。
例如,要检测 host.name
和 os.type
属性,可以使用系统检测器:
processors:resourcedetection:detectors: [env, system]service:pipelines:metrics:receivers: [otlp, hostmetrics]processors: [batch, resourcedetection]exporters: [otlp/uptrace]
要添加自定义属性,如 IP 地址,你可以使用 env 变量和 env
检测器:
export OTEL_RESOURCE_ATTRIBUTES="instance=127.0.0.1"
为了检测更多的信息,您可以使用更专门的检测器,例如,如果您正在使用 Amazon EC2,您可以使用 ec2
检测器来发现 cloud.region
和 cloud.availability_zone
属性:
processors:resourcedetection/ec2:detectors: [env, ec2]
如果您正在使用 Google Cloud:
processors:resourcedetection/gcp:detectors: [env, gcp]
如果你正在使用 Docker:
processors:resourcedetection/docker:detectors: [env, docker]
您可以查看官方文档,了解 Heroku、Azure、Consul 和许多其他可用的检测器。
https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#system-metadata 内存限制器 memorylimiterprocessor 是一个组件,允许用户在处理遥测数据时限制 OpenTelemetry Collector 消耗的内存量。它可以防止收集器使用过多的内存,这可能导致性能问题甚至崩溃。
https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md Memory Limiter Processor 的工作方式是定期检查 OpenTelemetry Collector 消耗的内存量,并将其与用户定义的内存限制进行比较。如果收集器使用的内存超过指定的限制,处理器将开始丢弃遥测数据,直到内存使用低于限制。
要启用内存限制器:
processors:memory_limiter:check_interval: 1slimit_mib: 4000spike_limit_mib: 800service:pipelines:metrics:processors: [memory_limiter]
OpenTelemetry 主机指标 hostmetricsreceiver 是一个 OpenTelemetry Collector plugin,它收集关于主机系统的各种指标,例如,CPU, RAM,磁盘指标和其他系统级指标。
https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver 通过收集和分析主机指标,您可以深入了解主机系统的性能和运行状况,并识别可能影响应用程序和服务整体性能的潜在问题或瓶颈。
主机指标 要开始收集主机指标,您需要在要监视的每个系统上安装 Collector,并将以下行添加到 Collector 配置中:
processors:resourcedetection:detectors: [env, system]cumulativetodelta:receivers:hostmetrics:collection_interval: 10sscrapers:# CPU utilization metricscpu:# Disk I/O metricsdisk:# File System utilization metricsfilesystem:# CPU load metricsload:# Memory utilization metricsmemory:# Network interface I/O metrics & TCP connection metricsnetwork:# Paging/Swap space utilization and I/O metricspaging:service:pipelines:metrics:receivers: [otlp, hostmetrics]processors: [cumulativetodelta, batch, resourcedetection]exporters: [otlp/uptrace]
文件系统指标 如果您使用的是不常见的文件系统,您可能需要更彻底地配置 filesystem
接收器,例如,只抓取支持的文件系统类型并避免警告:
receivers:hostmetrics:collection_interval: 10sscrapers:cpu:disk:load:filesystem:include_fs_types:match_type: strictfs_types: [ext3, ext4]memory:network:paging:
进程指标 要收集每个进程的 CPU、内存和磁盘 I/O 指标,您需要启用各自的抓取器:
receivers:hostmetrics:collection_interval: 10sscrapers:# Process count metricsprocess:# Per process CPU, Memory, and Disk I/O metricsprocesses:
这些抓取器在默认情况下是禁用的,因为它们需要以更高的权限运行 OpenTelemetry Collector 才能访问其他进程的信息。
在 Linux 上,你可以在 root
用户下运行 otelcol-contrib
:
# /lib/systemd/system/otelcol-contrib.serviceUser=rootGroup=root
或者使用 sudo
启动该进程:
# /lib/systemd/system/otelcol-contrib.serviceExecStart=sudo /usr/bin/otelcol-contrib $OTELCOL_OPTIONS
容器主机指标 在 Linux 上,OpenTelemetry 从 Linux 系统目录收集指标。要收集关于主机系统而不是容器的指标,可以在运行容器时挂载主机文件系统:
# mount the entire filesystemdocker run -v /:/hostfs ...# or mount only parts you needdocker run -v /proc:/hostfs/proc ...
然后配置 root_path
,以便 hostmetrics 接收器知道根文件系统的位置:
receivers:hostmetrics:root_path: /hostfs
Refs https://opentelemetry.io/ https://uptrace.dev/opentelemetry/