Documentation ¶
Overview ¶
Package obsreport provides unified and consistent observability signals ( metrics, tracing, etc) for components of the OpenTelemetry collector.
The function Configure is used to control which signals are going to be generated. It provides functions for the typical operations of receivers, processors, and exporters.
Receivers should use the respective start and end according to the data type being received, ie.:
TraceData receive operations should use the pair: StartTraceDataReceiveOp/EndTraceDataReceiveOp
Metrics receive operations should use the pair: StartMetricsReceiveOp/EndMetricsReceiveOp
Similar for exporters:
TraceData export operations should use the pair: StartTraceDataExportOp/EndTraceDataExportOp
Metrics export operations should use the pair: StartMetricsExportOp/EndMetricsExportOp
The package is capable of generating legacy metrics by using the observability package allowing a controlled transition from legacy to the new metrics. The goal is to eventually remove the legacy metrics and use only the new metrics.
The main differences regarding the legacy metrics are:
1. "Amount of metric data" is measured as metric points (ie.: a single value in time), contrast it with number of time series used legacy. Number of metric data points is a more general concept regarding various metric formats.
2. Exporters measure the number of items, ie.: number of spans or metric points, that were sent and the ones for which the attempt to send failed. For more information about this see Notes below about reporting data loss.
3. All measurements of "amount of data" used in the new metrics for receivers and exporters should reflect their native formats, not the internal format used in the Collector. This is to facilitate reconciliation between Collector, client and backend. For instance: certain metric formats do not provide direct support for histograms and have predefined conventions to represent those, this conversion may end with a different number of time series and data points than the internal Collector format.
Notes:
* Data loss should be recorded only when the component itself remove the data from the pipeline. Legacy metrics for receivers used "dropped" in their names but these could be non-zero under normal operations and reflected no actual data loss when exporters with "sending_queue" are used. New metrics were renamed to avoid this misunderstanding. Here are the general recommendations to report data loss:
Receivers reporting errors to clients typically result in the client re-sending the same data so it is more correct to report "receive errors", not actual data loss.
Exporters need to report individual failures to send data, but on typical production pipelines processors usually take care of retries, so these should be reported as "send errors".
Data "filtered out" should have its own metrics and not be confused with dropped data.
Naming Convention for New Metrics ¶
Common Metrics: Metrics shared by different components should follow the convention below:
`<component>/<metric_name>`
As a label the metric should have at least `{<component>="<name>"}` where `<name>` is the name used in the configuration for the instance of the component, eg.:
`receiver/accepted_spans{receiver="opencensus",...}` `exporter/sent_spans{exporter="jaeger/prod",...}`
Component Specific Metrics: These metrics are implemented by specific components, eg.: batch processor. The general pattern is the same as the common metrics but with the addition of the component type (as it appears in the configuration) before the actual metric:
`<component>/<type>/<metric_name>`
Even metrics exclusive to a single type should follow the conventions above and also include the type (as written in the configuration) as part of the metric name since there could be multiple instances of the same type in different pipelines, eg.:
`processor/batch/batch_size_trigger_send{processor="batch/dev",...}`
Index ¶
- Constants
- func AllViews() (views []*view.View)
- func BuildProcessorCustomMetricName(configType, metric string) string
- func Configure(level configtelemetry.Level) (views []*view.View)
- func EndLogsReceiveOp(receiverCtx context.Context, format string, numReceivedLogRecords int, ...)
- func EndMetricsReceiveOp(receiverCtx context.Context, format string, numReceivedPoints int, err error)
- func EndMetricsScrapeOp(scraperCtx context.Context, numScrapedMetrics int, err error)
- func EndTraceDataReceiveOp(receiverCtx context.Context, format string, numReceivedSpans int, err error)
- func GRPCServerWithObservabilityEnabled(extraOpts ...grpc.ServerOption) *grpc.Server
- func ProcessorMetricViews(configType string, legacyViews []*view.View) []*view.View
- func ReceiverContext(ctx context.Context, receiverID config.ComponentID, transport string) context.Context
- func ScraperContext(ctx context.Context, receiverID config.ComponentID, scraper config.ComponentID) context.Context
- func StartLogsReceiveOp(operationCtx context.Context, receiverID config.ComponentID, transport string, ...) context.Context
- func StartMetricsReceiveOp(operationCtx context.Context, receiverID config.ComponentID, transport string, ...) context.Context
- func StartMetricsScrapeOp(scraperCtx context.Context, receiverID config.ComponentID, ...) context.Context
- func StartTraceDataReceiveOp(operationCtx context.Context, receiverID config.ComponentID, transport string, ...) context.Context
- type Exporter
- func (eor *Exporter) EndLogsExportOp(ctx context.Context, numLogRecords int, err error)
- func (eor *Exporter) EndMetricsExportOp(ctx context.Context, numMetricPoints int, err error)
- func (eor *Exporter) EndTracesExportOp(ctx context.Context, numSpans int, err error)
- func (eor *Exporter) StartLogsExportOp(ctx context.Context) context.Context
- func (eor *Exporter) StartMetricsExportOp(ctx context.Context) context.Context
- func (eor *Exporter) StartTracesExportOp(ctx context.Context) context.Context
- type ExporterSettings
- type Processor
- func (por *Processor) LogsAccepted(ctx context.Context, numRecords int)
- func (por *Processor) LogsDropped(ctx context.Context, numRecords int)
- func (por *Processor) LogsRefused(ctx context.Context, numRecords int)
- func (por *Processor) MetricsAccepted(ctx context.Context, numPoints int)
- func (por *Processor) MetricsDropped(ctx context.Context, numPoints int)
- func (por *Processor) MetricsRefused(ctx context.Context, numPoints int)
- func (por *Processor) TracesAccepted(ctx context.Context, numSpans int)
- func (por *Processor) TracesDropped(ctx context.Context, numSpans int)
- func (por *Processor) TracesRefused(ctx context.Context, numSpans int)
- type ProcessorSettings
- type StartReceiveOption
- type StartReceiveOptions
Constants ¶
const ( // ExporterKey used to identify exporters in metrics and traces. ExporterKey = "exporter" // SentSpansKey used to track spans sent by exporters. SentSpansKey = "sent_spans" // FailedToSendSpansKey used to track spans that failed to be sent by exporters. FailedToSendSpansKey = "send_failed_spans" // SentMetricPointsKey used to track metric points sent by exporters. SentMetricPointsKey = "sent_metric_points" // FailedToSendMetricPointsKey used to track metric points that failed to be sent by exporters. FailedToSendMetricPointsKey = "send_failed_metric_points" // SentLogRecordsKey used to track logs sent by exporters. SentLogRecordsKey = "sent_log_records" // FailedToSendLogRecordsKey used to track logs that failed to be sent by exporters. FailedToSendLogRecordsKey = "send_failed_log_records" )
const ( // ProcessorKey is the key used to identify processors in metrics and traces. ProcessorKey = "processor" // DroppedSpansKey is the key used to identify spans dropped by the Collector. DroppedSpansKey = "dropped_spans" // DroppedMetricPointsKey is the key used to identify metric points dropped by the Collector. DroppedMetricPointsKey = "dropped_metric_points" // DroppedLogRecordsKey is the key used to identify log records dropped by the Collector. DroppedLogRecordsKey = "dropped_log_records" )
const ( // ReceiverKey used to identify receivers in metrics and traces. ReceiverKey = "receiver" // TransportKey used to identify the transport used to received the data. TransportKey = "transport" // FormatKey used to identify the format of the data received. FormatKey = "format" // AcceptedSpansKey used to identify spans accepted by the Collector. AcceptedSpansKey = "accepted_spans" // RefusedSpansKey used to identify spans refused (ie.: not ingested) by the Collector. RefusedSpansKey = "refused_spans" // AcceptedMetricPointsKey used to identify metric points accepted by the Collector. AcceptedMetricPointsKey = "accepted_metric_points" // RefusedMetricPointsKey used to identify metric points refused (ie.: not ingested) by the // Collector. RefusedMetricPointsKey = "refused_metric_points" // AcceptedLogRecordsKey used to identify log records accepted by the Collector. AcceptedLogRecordsKey = "accepted_log_records" // RefusedLogRecordsKey used to identify log records refused (ie.: not ingested) by the // Collector. RefusedLogRecordsKey = "refused_log_records" )
const ( // ScraperKey used to identify scrapers in metrics and traces. ScraperKey = "scraper" // ScrapedMetricPointsKey used to identify metric points scraped by the // Collector. ScrapedMetricPointsKey = "scraped_metric_points" // ErroredMetricPointsKey used to identify metric points errored (i.e. // unable to be scraped) by the Collector. ErroredMetricPointsKey = "errored_metric_points" )
Variables ¶
This section is empty.
Functions ¶
func BuildProcessorCustomMetricName ¶
BuildProcessorCustomMetricName is used to be build a metric name following the standards used in the Collector. The configType should be the same value used to identify the type on the config.
func Configure ¶
func Configure(level configtelemetry.Level) (views []*view.View)
Configure is used to control the settings that will be used by the obsreport package.
func EndLogsReceiveOp ¶ added in v0.15.0
func EndLogsReceiveOp( receiverCtx context.Context, format string, numReceivedLogRecords int, err error, )
EndLogsReceiveOp completes the receive operation that was started with StartLogsReceiveOp.
func EndMetricsReceiveOp ¶
func EndMetricsReceiveOp( receiverCtx context.Context, format string, numReceivedPoints int, err error, )
EndMetricsReceiveOp completes the receive operation that was started with StartMetricsReceiveOp.
func EndMetricsScrapeOp ¶ added in v0.14.0
EndMetricsScrapeOp completes the scrape operation that was started with StartMetricsScrapeOp.
func EndTraceDataReceiveOp ¶
func EndTraceDataReceiveOp( receiverCtx context.Context, format string, numReceivedSpans int, err error, )
EndTraceDataReceiveOp completes the receive operation that was started with StartTraceDataReceiveOp.
func GRPCServerWithObservabilityEnabled ¶ added in v0.6.0
func GRPCServerWithObservabilityEnabled(extraOpts ...grpc.ServerOption) *grpc.Server
GRPCServerWithObservabilityEnabled creates a gRPC server that at a bare minimum has the OpenCensus ocgrpc server stats handler enabled for tracing and stats. Use it instead of invoking grpc.NewServer directly.
func ProcessorMetricViews ¶
ProcessorMetricViews builds the metric views for custom metrics of processors.
func ReceiverContext ¶
func ReceiverContext( ctx context.Context, receiverID config.ComponentID, transport string, ) context.Context
ReceiverContext adds the keys used when recording observability metrics to the given context returning the newly created context. This context should be used in related calls to the obsreport functions so metrics are properly recorded.
func ScraperContext ¶ added in v0.14.0
func ScraperContext( ctx context.Context, receiverID config.ComponentID, scraper config.ComponentID, ) context.Context
ScraperContext adds the keys used when recording observability metrics to the given context returning the newly created context. This context should be used in related calls to the obsreport functions so metrics are properly recorded.
func StartLogsReceiveOp ¶ added in v0.15.0
func StartLogsReceiveOp( operationCtx context.Context, receiverID config.ComponentID, transport string, opt ...StartReceiveOption, ) context.Context
StartLogsReceiveOp is called when a request is received from a client. The returned context should be used in other calls to the obsreport functions dealing with the same receive operation.
func StartMetricsReceiveOp ¶
func StartMetricsReceiveOp( operationCtx context.Context, receiverID config.ComponentID, transport string, opt ...StartReceiveOption, ) context.Context
StartMetricsReceiveOp is called when a request is received from a client. The returned context should be used in other calls to the obsreport functions dealing with the same receive operation.
func StartMetricsScrapeOp ¶ added in v0.14.0
func StartMetricsScrapeOp( scraperCtx context.Context, receiverID config.ComponentID, scraper config.ComponentID, ) context.Context
StartMetricsScrapeOp is called when a scrape operation is started. The returned context should be used in other calls to the obsreport functions dealing with the same scrape operation.
func StartTraceDataReceiveOp ¶
func StartTraceDataReceiveOp( operationCtx context.Context, receiverID config.ComponentID, transport string, opt ...StartReceiveOption, ) context.Context
StartTraceDataReceiveOp is called when a request is received from a client. The returned context should be used in other calls to the obsreport functions dealing with the same receive operation.
Types ¶
type Exporter ¶ added in v0.23.0
type Exporter struct {
// contains filtered or unexported fields
}
Exporter is a helper to add observability to a component.Exporter.
func NewExporter ¶ added in v0.23.0
func NewExporter(cfg ExporterSettings) *Exporter
NewExporter creates a new Exporter.
func (*Exporter) EndLogsExportOp ¶ added in v0.23.0
EndLogsExportOp completes the export operation that was started with StartLogsExportOp.
func (*Exporter) EndMetricsExportOp ¶ added in v0.23.0
EndMetricsExportOp completes the export operation that was started with StartMetricsExportOp.
func (*Exporter) EndTracesExportOp ¶ added in v0.23.0
EndTracesExportOp completes the export operation that was started with StartTracesExportOp.
func (*Exporter) StartLogsExportOp ¶ added in v0.23.0
StartLogsExportOp is called at the start of an Export operation. The returned context should be used in other calls to the Exporter functions dealing with the same export operation.
func (*Exporter) StartMetricsExportOp ¶ added in v0.23.0
StartMetricsExportOp is called at the start of an Export operation. The returned context should be used in other calls to the Exporter functions dealing with the same export operation.
func (*Exporter) StartTracesExportOp ¶ added in v0.23.0
StartTracesExportOp is called at the start of an Export operation. The returned context should be used in other calls to the Exporter functions dealing with the same export operation.
type ExporterSettings ¶ added in v0.24.0
type ExporterSettings struct { Level configtelemetry.Level ExporterID config.ComponentID }
ExporterSettings are settings for creating an Exporter.
type Processor ¶ added in v0.23.0
type Processor struct {
// contains filtered or unexported fields
}
Processor is a helper to add observability to a component.Processor.
func NewProcessor ¶ added in v0.23.0
func NewProcessor(cfg ProcessorSettings) *Processor
NewProcessor creates a new Processor.
func (*Processor) LogsAccepted ¶ added in v0.23.0
LogsAccepted reports that the logs were accepted.
func (*Processor) LogsDropped ¶ added in v0.23.0
LogsDropped reports that the logs were dropped.
func (*Processor) LogsRefused ¶ added in v0.23.0
LogsRefused reports that the logs were refused.
func (*Processor) MetricsAccepted ¶ added in v0.23.0
MetricsAccepted reports that the metrics were accepted.
func (*Processor) MetricsDropped ¶ added in v0.23.0
MetricsDropped reports that the metrics were dropped.
func (*Processor) MetricsRefused ¶ added in v0.23.0
MetricsRefused reports that the metrics were refused.
func (*Processor) TracesAccepted ¶ added in v0.23.0
TracesAccepted reports that the trace data was accepted.
func (*Processor) TracesDropped ¶ added in v0.23.0
TracesDropped reports that the trace data was dropped.
type ProcessorSettings ¶ added in v0.23.0
type ProcessorSettings struct { Level configtelemetry.Level ProcessorID config.ComponentID }
ProcessorSettings are settings for creating a Processor.
type StartReceiveOption ¶
type StartReceiveOption func(*StartReceiveOptions)
StartReceiveOption function applues changes to StartReceiveOptions.
func WithLongLivedCtx ¶
func WithLongLivedCtx() StartReceiveOption
WithLongLivedCtx indicates that the context passed in the call outlives the receive operation at hand. Typically the long lived context is associated to a connection, eg.: a gRPC stream or a TCP connection, for which many batches of data are received in individual operations without a corresponding new context per operation.
Example:
func (r *receiver) ClientConnect(ctx context.Context, rcvChan <-chan pdata.Traces) { longLivedCtx := obsreport.ReceiverContext(ctx, r.config.Name(), r.transport, "") for { // Since the context outlives the individual receive operations call obsreport using // WithLongLivedCtx(). ctx := obsreport.StartTraceDataReceiveOp( longLivedCtx, r.config.Name(), r.transport, obsreport.WithLongLivedCtx()) td, ok := <-rcvChan var err error if ok { err = r.nextConsumer.ConsumeTraces(ctx, td) } obsreport.EndTraceDataReceiveOp( ctx, r.format, len(td.Spans), err) if !ok { break } } }
type StartReceiveOptions ¶
type StartReceiveOptions struct { // LongLivedCtx when true indicates that the context passed in the call // outlives the individual receive operation. See WithLongLivedCtx() for // more information. LongLivedCtx bool }
StartReceiveOptions has the options related to starting a receive operation.