Documentation with latest guidance, and adjust types accordingly #69
Conversation
|
@ktoso Thanks for getting this started 🙏 I really like having the different DocC guides for the three different implementation use cases 👍 |
|
Yup, we'll separate it out and give lots of examples. I'll spend time tomorrow on this and will ask for a review. |
|
Today I rewrote the |
| ### Libraries & Frameworks | ||
| ## Libraries & Frameworks | ||
|
|
||
| For distributed tracing to be most useful, it needs to be integrated in libraries, especially those serving to inter-connect different processes such as HTTP, or other RPC clients/servers. This then enables end users to reap the benefits of automatic trace propagation across nodes in a system, as well as restoring baggage when incoming messages are received by such library/framework. |
There was a problem hiding this comment.
| For distributed tracing to be most useful, it needs to be integrated in libraries, especially those serving to inter-connect different processes such as HTTP, or other RPC clients/servers. This then enables end users to reap the benefits of automatic trace propagation across nodes in a system, as well as restoring baggage when incoming messages are received by such library/framework. | |
| For distributed tracing to be most useful, it needs to be integrated in libraries, especially those serving to inter-connect different processes such as HTTP or other RPC clients/servers. This then enables end users to reap the benefits of automatic trace propagation across nodes in a system, as well as restoring baggage when incoming messages are received by such library/framework. |
|
|
||
| For distributed tracing to be most useful, it needs to be integrated in libraries, especially those serving to inter-connect different processes such as HTTP, or other RPC clients/servers. This then enables end users to reap the benefits of automatic trace propagation across nodes in a system, as well as restoring baggage when incoming messages are received by such library/framework. | ||
|
|
||
| The table below illustrates the |
|
|
||
| Distributed tracing offers two types of instrumentation protocols: an instrument, and a tracer. | ||
|
|
||
| A tracer is-an instrument as well, and further refines it with the ability to start a trace ``Span``. |
There was a problem hiding this comment.
| A tracer is-an instrument as well, and further refines it with the ability to start a trace ``Span``. | |
| A tracer is an instrument as well, and further refines it with the ability to start a trace ``Span``. |
|
|
||
| When your library/framework can benefit from tracing, you should make use of it by integrating the `Tracing` library. | ||
|
|
||
| In order to work with the tracer [configured by the end-user](#Bootstrapping-the-Instrumentation-System), it adds a property to `InstrumentationSystem` that gives you back a `Tracer`. You can then use that tracer to start `Span`s. In an HTTP client you e.g. |
There was a problem hiding this comment.
Inconsistent use of end-user vs "end user"
Co-authored-by: Yim Lee <[email protected]>
Co-authored-by: Yim Lee <[email protected]>
Co-authored-by: Konrad `ktoso` Malawski <[email protected]>
| .target( | ||
| name: "MyApplication", | ||
| dependencies: [ | ||
| .product(name: "OpenTelemetry", package: "opentelemetry-swift"), |
There was a problem hiding this comment.
Maybe should include OtlpGRPCSpanExporting from very start?
There was a problem hiding this comment.
For what it's worth this might better be "SomeTracingSystem" and not the otel not to confuse people. We just happen to use otel in the examples below, but this just explains adding a dependency 🤔 I'll think some more how to do this well.
|
|
||
| A typical bootstrap could look something like this: | ||
|
|
||
| ```swift |
There was a problem hiding this comment.
Maybe keep this as a full example (with MultiThreadedEventLoopGroup) and remove the bootstrapping the tracer above since this is a more complete example and having the two very close to each other is duplication?
There was a problem hiding this comment.
And also add a note about BatchSpanProcessor vs SimpleSpanProcessor. As simple processor is not suitable for hot code execution as will lead to 700+ byte message being sent each time the span is executed.
There was a problem hiding this comment.
I'm a bit torn about this... This isn't the otel tracer's guide. For what it's worth this should be "go and read a specific tracer impls docs" but I want something good enough here to get someone started.
I'll see how to improve this bit though
| The primary way you interact with distributed tracing is by starting ``Span``s. | ||
|
|
||
| Spans form hierarchies with their parent spans, and end up being visualized using various tools, usually in a format similar to gant charts. So for example, if we had multiple operations that compose making dinner, they would be modelled as child spans of a main `makeDinner` span. Any sub tasks are again modelled as child spans of any given operation, and so on. | ||
|
|
There was a problem hiding this comment.
There was a problem hiding this comment.
Yeha might as well, We're not "limited to" otel but they have some good guides, I'll add a links
ktoso
changed the title
ktoso
changed the title
ktoso
changed the title
|
I'm going to revive the docs now, but probably by making it a new PR |
|
Replaced by #121 |
Work in progress
Revamp the docs and do the final renames before heading towards 1.0
Resolves #80