Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SDK tracing: clarify multi-processors scenarios #338

Merged
merged 13 commits into from
Dec 4, 2019
Merged

SDK tracing: clarify multi-processors scenarios #338

Changes from 12 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
b357525
Recommend chaining on processors
Oct 26, 2019
9724a8c
fix lint
Oct 26, 2019
dac6f49
fix lint2
Oct 26, 2019
9cf2f48
example for span chaining
Oct 29, 2019
0634a69
fix formatting
Oct 29, 2019
3cea141
Update sdk-tracing.md
Oct 30, 2019
4e469e7
Update sdk-tracing.md
Oct 30, 2019
ab69437
Update sdk-tracing.md
Oct 30, 2019
0a9ef03
remove advanced example, do not encourage implementing helpers in the…
Nov 11, 2019
238945f
recommend to move implement new common processing scearios out-of-proc
Nov 11, 2019
f92579f
fix lint
Nov 12, 2019
7761327
BatchProcessor -> BatchEporterProcessor
Nov 23, 2019
6e6bda3
Merge branch 'master' into patch-3
SergeyKanzhelev Dec 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 30 additions & 24 deletions specification/sdk-tracing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,9 +144,10 @@ held by the `Tracer`.

Span processor is an interface which allows hooks for span start and end method
invocations. The span processors are invoked only when
[`IsRecording`](api-tracing.md#isrecording) is true. This interface
must be used to implement [span exporter](#span-exporter) to batch and convert
spans.
[`IsRecording`](api-tracing.md#isrecording) is true.

Built-in span processors are responsible for batching and conversion of spans to
exportable representation and passing batches to exporters.

Span processors can be registered directly on SDK `TracerFactory` and they are
invoked in the same order as they were registered.
Expand All @@ -161,22 +162,29 @@ Manipulation of the span processors collection must only happen on `TracerFactor
instances. This means methods like `addSpanProcessor` must be implemented on
`TracerFactory`.

Each processor registered on `TracerFactory` is a start of pipeline that consist
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lmolkova I understand that you are clarifying the document and not suggesting new functionality but if you don't mind I would like to bring attention of approvers to this issue while we are working on this part of the spec.

@open-telemetry/specs-approvers what are the arguments for having multi-pipeline feature in-process rather than use the already existing equivalent functionality in OpenTelemetry Collector? In my opinion this could be removed from the SDK and we encourage using Collector for this, but perhaps there are use cases that I am not aware of that require this to be in SDK.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it can be removed from SDK. There are definitely cases when collector cannot be installed. Also some spans can be filtered out right from the process to save on cross-proc communication with collector.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tigrannajaryan for the z-pages functionality that we want to support it is inefficient to stream everything to the collector. So at least one example that we want to support is:

  • Send all spans that record events to the z-pages span processor
  • Send all sampled spans to the configure exporter (collector probably)

Copy link
Member

@mtwo mtwo Nov 22, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to Sergey and Bogdan's comments

I don't think that having equivalent functionality is bad in this case (and I say this as someone who expects most of their customers to use the collector). As Sergey mentioned, there will always be cases where people can't use the collector or where it doesn't add much value.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

of span processor and optional exporter. SDK MUST allow to end each pipeline with
individual exporter.

SDK MUST allow users to implement and configure custom processors and decorate
built-in processors for advanced scenarios such as tagging or filtering.

The following diagram shows `SpanProcessor`'s relationship to other components
in the SDK:

```
+-----+---------------+ +---------------------+ +-------------------+
| | | | | | |
| | | | BatchProcessor | | SpanExporter |
| | +---> SimpleProcessor +---> (JaegerExporter) |
| SDK | SpanProcessor | | | | |
| | | +---------------------+ +-------------------+
| | |
| | | +---------------------+
| | | | |
| | +---> ZPagesProcessor |
| | | | |
+-----+---------------+ +---------------------+
+-----+--------------+ +-------------------------+ +-------------------+
| | | | | | |
| | | | BatchExporterProcessor | | SpanExporter |
| | +---> SimpleExporterProcessor +---> (JaegerExporter) |
| | | | | | |
| SDK | Span.start() | +-------------------------+ +-------------------+
| | Span.end() |
| | | +---------------------+
| | | | |
| | +---> ZPagesProcessor |
| | | | |
+-----+--------------+ +---------------------+
```

#### Interface definition
Expand Down Expand Up @@ -217,6 +225,10 @@ they want to make the shutdown timeout to be configurable.

#### Built-in span processors

SDK MUST implement simple and batch processors described below. Other common
processing scenarios should be first considered for implementation out-of-process
in [OpenTelemetry Collector](overview.md#collector)

##### Simple processor

The implementation of `SpanProcessor` that passes ended span directly to the
Expand Down Expand Up @@ -254,15 +266,9 @@ high contention in a very high traffic service.
implement so that they can be plugged into OpenTelemetry SDK and support sending
of telemetry data.

The goals of the interface are:

* Minimize burden of implementation for protocol-dependent telemetry exporters.
The protocol exporter is expected to be primarily a simple telemetry data
encoder and transmitter.
* Allow implementing helpers as composable components that use the same
chainable `Exporter` interface. SDK authors are encouraged to implement common
functionality such as queuing, batching, tagging, etc. as helpers. This
functionality will be applicable regardless of what protocol exporter is used.
The goal of the interface is to minimize burden of implementation for
protocol-dependent telemetry exporters. The protocol exporter is expected to be
primarily a simple telemetry data encoder and transmitter.

#### Interface Definition

Expand Down