Adds tracing documentation #1039
Conversation
docs/basics/tracing.md
Outdated
| app.get("fetchAndProcessNIO") { req in | ||
| withSpan("fetch", context: req.serviceContext) { span in | ||
| fetchSomething().map { result in | ||
| withSpan("process", context: span) { _ in |
There was a problem hiding this comment.
| withSpan("process", context: span) { _ in | |
| withSpan("process", context: span.context) { _ in |
There was a problem hiding this comment.
Ah, good catch! I've fixed it. Thanks!
NeedleInAJayStack
force-pushed
the
tracing
branch
from
63f8eec to
a7138ec
Compare
docs/basics/tracing.md
Outdated
There was a problem hiding this comment.
I've moved it to the advanced section.
docs/basics/tracing.md
Outdated
|
|
||
| Vapor's tracing API is built on top of [swift-distributed-tracing](https://github.com/apple/swift-distributed-tracing), which means it is compatible with all of swift-distributed-tracing's [backend implementations](https://github.com/apple/swift-distributed-tracing/blob/main/README.md#tracing-backends). | ||
|
|
||
| If unfamiliar with tracing and spans in Swift, review the [OpenTelemetry Trace documentation](https://opentelemetry.io/docs/concepts/signals/traces/) and [swift-distributed-tracing documentation](https://swiftpackageindex.com/apple/swift-distributed-tracing/main/documentation/tracing). |
There was a problem hiding this comment.
| If unfamiliar with tracing and spans in Swift, review the [OpenTelemetry Trace documentation](https://opentelemetry.io/docs/concepts/signals/traces/) and [swift-distributed-tracing documentation](https://swiftpackageindex.com/apple/swift-distributed-tracing/main/documentation/tracing). | |
| If you are unfamiliar with tracing and spans in Swift, review the [OpenTelemetry Trace documentation](https://opentelemetry.io/docs/concepts/signals/traces/) and [swift-distributed-tracing documentation](https://swiftpackageindex.com/apple/swift-distributed-tracing/main/documentation/tracing). |
docs/basics/tracing.md
Outdated
|
|
||
| ## TracingMiddleware | ||
|
|
||
| To automatically create a fully annotated span for each request, add the `TracingMiddleware` to your application. |
There was a problem hiding this comment.
We should add a note about this being added before any middleware that will make requests to external services
There was a problem hiding this comment.
Good idea. Done!
docs/basics/tracing.md
Outdated
|
|
||
| ## TracingMiddleware | ||
|
|
||
| To automatically create a fully annotated span for each request, add the `TracingMiddleware` to your application. |
There was a problem hiding this comment.
Good idea. Done!
docs/basics/tracing.md
Outdated
There was a problem hiding this comment.
I've moved it to the advanced section.
docs/advanced/tracing.md
Outdated
| app.middleware.use(TracingMiddleware()) | ||
| ``` | ||
|
|
||
| To ensure that tracing identifiers are passed along correctly, this should be added before any middleware that calls tracing APIs or connects to external services. |
There was a problem hiding this comment.
I'd go a step further and say that TracingMiddleware should be as early as possible in the chain, because the sooner this is invoked the more honest is the duration of the span in relation to actual response time.
There was a problem hiding this comment.
Great point. I've adjusted it to say that it should be added as early as possible.
Adds new Tracing chapter to document API introduced in vapor/vapor#3253