Vostok.Tracing.Abstractions
0.1.7
Prefix Reserved
See the version list below for details.
dotnet add package Vostok.Tracing.Abstractions --version 0.1.7
NuGet\Install-Package Vostok.Tracing.Abstractions -Version 0.1.7
<PackageReference Include="Vostok.Tracing.Abstractions" Version="0.1.7" />
paket add Vostok.Tracing.Abstractions --version 0.1.7
#r "nuget: Vostok.Tracing.Abstractions, 0.1.7"
// Install Vostok.Tracing.Abstractions as a Cake Addin #addin nuget:?package=Vostok.Tracing.Abstractions&version=0.1.7 // Install Vostok.Tracing.Abstractions as a Cake Tool #tool nuget:?package=Vostok.Tracing.Abstractions&version=0.1.7
Vostok tracing
Distributed tracing allows to reconstruct the history of the logical operation spanning many applications and machines in time as a tree of smaller actions or events called spans. Spans can represent HTTP requests, database queries or any other significant interactions or events in a distributed system. A single span always describes a local event in a single process: an HTTP request usually produces two spans (client-side and server-side). Each kind of span stores specific information about performed action.
<br/>
- Span structure
- Common annotations
- Kind-specific annotations
- Queue tracing conventions
<br/>
Span structure
Every span consists of following fields:
TraceId
— unique identifier of the trace containing the span (Guid).- Gets assigned on first operation (usually on a front-end application instance).
- Serves as a correlation identifier between spans
SpanId
— unique identifier of the span itself (Guid).ParentSpanId
— identifier of the parent span in the tree (Guid).- May be absent for root span in the tree.
BeginTimestamp
— beginning timestamp of the event or interaction described by this span (UTC timestamp + timezone offset).EndTimestamp
— ending timestamp of the event or interaction described by this span (UTC timestamp + timezone offset).- Always measured with the same clock as
BeginTimestamp
. This allows to derive span duration as a difference betweenEndTimestamp
andBeginTimestamp
. - May be absent for a special kind of 'endless' spans described further.
- Always measured with the same clock as
Annotations
— payload in key-value format (string --> object). Keys are case-sensitive.
<br/>
Common annotations
These are the annotations relevant for any span:
Name | Description |
---|---|
kind |
Span kind. There are a number of predefined span kinds for common use cases (e.g. http-request-server ). |
operation |
Human-readable logical operation or event name (e.g. create-user ). |
status |
Logical operation or event status (success , error , or warning ). Might not have operation-specific values. |
application |
Name of the application the span originated from. |
environment |
Name of the environment the span originated from. |
host |
DNS name of the host the span originated from. |
component |
Name of a library or component in code responsible for producing the span. |
<br/> <br/>
Kind-specific annotations
HTTP requests
Common annotations for all spans related to HTTP requests:
Name | Description | Default value |
---|---|---|
operation |
See common annotations. | {http.request.method} {normalized http.request.url} . Example: POST /page/{num}/process |
http.request.method |
Request method (e.g. GET , POST , PUT , etc). |
N/A |
http.request.url |
Request URL without query parameters. | N/A |
http.request.size |
Request body size in bytes. | N/A |
http.response.code |
Response code (e.g. 200 or 404 ). |
N/A |
http.response.size |
Response body size in bytes. | N/A |
Normalized URL is a short URL without scheme, authority and query parameters. Unique path segments (entity ids, search queries, hex values) are replaced with placeholders. Example before and after normalization: http://vm-app1/users/a534bcbd/
--> users/{id}
<br/>
HTTP client (direct)
Submitting an HTTP request directly to an external URL or a service replica.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | http-request-client |
http.request.targetService |
Name of the service to which request is sent. | N/A |
http.request.targetEnvironment |
Name of the environment to which request is sent. | N/A |
<br/>
HTTP client (cluster)
Submitting an HTTP request to a clustered application with several replicas.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | http-request-cluster |
http.cluster.strategy |
Name of the strategy used to send request (e.g. sequential , parallel , ...) |
N/A |
http.cluster.status |
Status of interaction with a cluster (e.g. success , no-replicas , ...) |
N/A |
http.request.targetService |
Name of the service to which request is sent. | N/A |
http.request.targetEnvironment |
Name of the environment to which request is sent. | N/A |
<br/>
HTTP server
Handling an HTTP request on server.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | http-request-server |
http.client.name |
Name of the client application that sent the request. | N/A |
http.client.address |
Address of the client application instance (host name or IP address). | N/A |
<br/> <br/>
Custom (not HTTP) requests
Common annotations for all spans related to custom requests:
Name | Description | Default value |
---|---|---|
operation |
See common annotations. | N/A |
status |
See common annotations. | N/A |
custom.response.status |
Custom request-specific status. | N/A |
custom.request.size |
Request size in bytes. | N/A |
custom.response.size |
Response size in bytes. | N/A |
custom.request.targetService |
Name of the service to which request is sent. | N/A |
custom.request.targetEnvironment |
Name of the environment to which request is sent. | N/A |
<br/>
Custom (not HTTP) client (direct)
Submitting custom request directly to a service replica.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | custom-request-client |
custom.request.replica |
Name of the replica to which request is sent. | N/A |
<br/>
Custom (not HTTP) client (cluster)
Submitting custom request to a clustered application with several replicas.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | custom-request-cluster |
<br/> <br/>
Custom operations
Performing custom server operation.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | custom-operation |
operation |
See common annotations. | N/A |
status |
See common annotations. | N/A |
custom.operation.status |
Custom operation-specific status. | N/A |
custom.operation.size |
Processed data size in bytes. | N/A |
custom.operation.targetService |
Name of the service with which this operation is associated. | {application} |
custom.operation.targetEnvironment |
Name of the environment with which this operation is associated. | {environment} |
<br/> <br/>
Database requests
Submitting a request to database.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | db-request |
operation |
See common annotations. Possible examples: read from table X , insert into table Z . |
N/A |
db.type |
Database type (mssql , cassandra , mongodb , elastic , etc). |
N/A |
db.instance |
Address of the database server instance (URL, hostname, connection string). | N/A |
... |
Any other database-specific annotations. | N/A |
MS SQL
TODO
Cassandra
TODO
MongoDB
TODO
ElasticSearch
TODO
<br/> <br/>
Distributed task queues
See queue tracing conventions for more context.
Common annotations for all spans related to distributed task queues:
Name | Description | Default value |
---|---|---|
queue.type |
Queue type (rabbit , etc). |
N/A |
queue.topic |
Name of the task type or the topic/queue it was inserted to. | N/A |
queue.taskId |
Task unique identifier. | N/A |
<br/>
Queue (producer)
A span that represents insertion of a task to queue (from the producer standpoint). Note that this span should not be in the same trace with subsequent spans related to inserted task: instead, it's connected with dedicated task trace with queue.taskTraceId
annotation.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | queue-producer |
operation |
See common annotations. | ({queue.type}) Put to '{queue.topic}' . Example: (echelon) Put to 'reports' . |
queue.actionResult |
Result of action (success , error , timeout or something else). |
N/A |
queue.taskTraceId |
Trace identifier assigned to the task. | N/A |
<br/>
Queue (task-lifecycle)
A span that represents whole lifecycle of the task in queue. It serves as a root span in the task's personal trace.
Spans of this kind are special in two ways:
- They are non-local: task lifecycle spans do not directly relate with events happening inside any single process.
- They do not have an ending timestamp: it must be inferred from the rightmost end timestamp of all the child spans.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | queue-task-lifecycle |
queue.producerTraceId |
Trace identifier of the producer's (client app that created the task) request. | N/A |
<br/>
Queue (task-lifecycle-event)
A span that represents an event that somehow changes task state.
Such spans usually have zero duration and are produced by brokers or client libraries.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | queue-task-lifecycle-event |
operation |
See common annotations. Examples: pass-to-consumer , prolong-execution , ... |
N/A |
queue.externalTraceId |
Trace identifier of the client app request that triggered the event (if any). | N/A |
... |
Any other operation-specific annotations. | N/A |
<br/>
Queue (consumer)
A span that represents execution of a queued task on the consumer.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | queue-consumer |
queue.executionResult |
Result of task execution (success , error , etc). Might have queue-specific values. |
N/A |
<br/>
Queue (manager)
A span that represents a management action on the task, but from the client's standpoint, as opposed to queue-task-lifecycle-event
spans. Note that this span should not be in the same trace with subsequent spans related to managed task.
Name | Description | Default value |
---|---|---|
kind |
See common annotations. | queue-manager |
operation |
See common annotations. Examples: delete , prolong-execution , ... |
N/A |
queue.actionResult |
Result of action (success , error , timeout or something else). |
N/A |
<br/> <br/>
Queue tracing conventions
Following conventions apply to tracing of queue tasks:
Each task should have a dedicated trace with a root span of
queue-task-lifecycle
kind. This span does not have an explicit end timestamp. It gets "stretched" by child spans instead.Each task should contain its personal
traceId
and root span'sspanId
embedded in content, available for consumers.Root lifecycle spans can have child spans of
queue-task-lifecycle-event
andqueue-consumer
kinds. External operations from producers and management clients happen in their own traces.A span of
queue-task-lifecycle-event
kind can have a link totraceId
of external operation that triggered the event.A span of
queue-producer
kind should have a link totraceId
of the produced task.
If a queue has no broker or there's no access to broker code, its tracing duties have to be performed by client libraries (creation of queue-task-lifecycle
and queue-task-lifecycle-event
spans).
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- No dependencies.
-
net6.0
- No dependencies.
NuGet packages (17)
Showing the top 5 NuGet packages that depend on Vostok.Tracing.Abstractions:
Package | Downloads |
---|---|
Vostok.Tracing.Extensions
This library contains a set of extensions for common case scenarios (such as HTTP request tracing). |
|
Vostok.ZooKeeper.Client
An implementation of ZooKeeper client. |
|
Vostok.Hosting
The entry point to create and launch Vostok-compatible services. |
|
Vostok.Hosting.Abstractions
Vostok.Hosting.Abstractions |
|
Vostok.Tracing
This library contains an implementation of core tracing interface (ITracer). |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.1.8-pre000021 | 9,139 | 9/14/2022 |
0.1.8-pre000020 | 11,635 | 7/28/2022 |
0.1.8-pre000019 | 1,865 | 3/28/2022 |
0.1.8-pre000018 | 186 | 12/30/2021 |
0.1.8-pre000017 | 180 | 12/30/2021 |
0.1.7 | 73,442 | 12/30/2021 |
0.1.7-pre000015 | 182 | 12/30/2021 |
0.1.7-pre000013 | 206 | 12/20/2021 |
0.1.7-pre000012 | 195 | 12/7/2021 |
0.1.6 | 21,842 | 12/7/2021 |
0.1.6-pre000010 | 200 | 12/6/2021 |
0.1.5 | 3,449 | 12/6/2021 |
0.1.5-pre000072 | 8,786 | 12/3/2020 |
0.1.5-pre000071 | 1,216 | 11/20/2020 |
0.1.5-pre000008 | 193 | 12/4/2021 |
0.1.5-pre000007 | 197 | 12/3/2021 |
0.1.5-pre000006 | 187 | 12/3/2021 |
0.1.5-pre000005 | 187 | 11/30/2021 |
0.1.5-pre000004 | 2,803 | 11/25/2021 |
0.1.5-pre000003 | 6,140 | 11/24/2021 |
0.1.5-pre000002 | 199 | 11/23/2021 |
0.1.5-pre000001 | 238 | 11/12/2021 |
0.1.4 | 108,956 | 11/20/2020 |
0.1.4-pre000066 | 6,480 | 6/17/2020 |
0.1.3 | 90,910 | 6/17/2020 |
0.1.3-pre000058 | 12,139 | 3/3/2020 |
0.1.3-pre000057 | 354 | 3/3/2020 |
0.1.2 | 75,007 | 3/3/2020 |
0.1.1 | 86,906 | 1/16/2020 |
0.1.1-pre000049 | 2,574 | 10/1/2019 |
0.1.1-pre000048 | 394 | 9/30/2019 |
0.1.1-pre000047 | 869 | 8/23/2019 |
0.1.1-pre000046 | 1,340 | 3/21/2019 |
0.1.0 | 96,499 | 3/21/2019 |
0.1.0-pre000044 | 436 | 3/21/2019 |
0.0.1-pre000043 | 1,056 | 1/16/2019 |
0.0.1-pre000042 | 1,356 | 9/27/2018 |
0.0.1-pre000041 | 598 | 9/27/2018 |
0.0.1-pre000040 | 1,478 | 9/14/2018 |
0.0.1-pre000039 | 632 | 9/14/2018 |
0.0.1-pre000038 | 821 | 9/13/2018 |
0.0.1-pre000037 | 647 | 9/13/2018 |
0.0.1-pre000036 | 644 | 9/12/2018 |
0.0.1-pre000035 | 610 | 9/12/2018 |
0.0.1-pre000034 | 635 | 9/12/2018 |
0.0.1-pre000033 | 623 | 9/12/2018 |
0.0.1-pre000032 | 637 | 9/12/2018 |
0.0.1-pre000031 | 704 | 9/10/2018 |
0.0.1-pre000030 | 727 | 9/7/2018 |
0.0.1-pre000029 | 660 | 9/7/2018 |
0.0.1-pre000028 | 666 | 9/7/2018 |
0.0.1-pre000027 | 680 | 9/7/2018 |
0.0.1-pre000026 | 651 | 9/7/2018 |
0.0.1-pre000025 | 628 | 9/4/2018 |
0.0.1-pre000024 | 621 | 9/4/2018 |
0.0.1-pre000023 | 683 | 9/4/2018 |
0.0.1-pre000022 | 672 | 9/4/2018 |
0.0.1-pre000021 | 620 | 8/30/2018 |
0.0.1-pre000020 | 601 | 8/30/2018 |
0.0.1-pre000019 | 643 | 8/30/2018 |
0.0.1-pre000018 | 618 | 8/30/2018 |
0.0.1-pre000017 | 607 | 8/30/2018 |
0.0.1-pre000016 | 659 | 8/30/2018 |
0.0.1-pre000015 | 756 | 8/26/2018 |
0.0.1-pre000014 | 732 | 8/24/2018 |
0.0.1-pre000013 | 720 | 8/24/2018 |
0.0.1-pre000012 | 676 | 8/23/2018 |
0.0.1-pre000011 | 659 | 8/23/2018 |
0.0.1-pre000010 | 656 | 8/22/2018 |
0.0.1-pre000009 | 833 | 8/21/2018 |
0.0.1-pre000008 | 764 | 8/21/2018 |
0.0.1-pre000007 | 749 | 8/20/2018 |
0.0.1-pre000006 | 1,033 | 8/20/2018 |
0.0.1-pre000005 | 693 | 8/20/2018 |
0.0.1-pre000004 | 905 | 8/17/2018 |
0.0.1-pre000003 | 665 | 8/17/2018 |
0.0.1-pre000002 | 674 | 8/16/2018 |
0.0.1-pre000001 | 697 | 8/16/2018 |