Vostok.Tracing.Abstractions 0.1.7

Prefix Reserved
.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
There is a newer prerelease version of this package available.
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
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Vostok.Tracing.Abstractions" Version="0.1.7" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Vostok.Tracing.Abstractions --version 0.1.7                

                    
                

            
#r "nuget: Vostok.Tracing.Abstractions, 0.1.7"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// 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

Build & Test & Publish NuGet

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/>

<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 between EndTimestamp and BeginTimestamp.
    • May be absent for a special kind of 'endless' spans described further.

  • 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:

  1. They are non-local: task lifecycle spans do not directly relate with events happening inside any single process.
  2. 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's spanId embedded in content, available for consumers.

  • Root lifecycle spans can have child spans of queue-task-lifecycle-event and queue-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 to traceId of external operation that triggered the event.

  • A span of queue-producer kind should have a link to traceId of the produced task.

General queue tracing scheme

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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

  • .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,165 9/14/2022
0.1.8-pre000020 11,843 7/28/2022
0.1.8-pre000019 1,868 3/28/2022
0.1.8-pre000018 186 12/30/2021
0.1.8-pre000017 180 12/30/2021
0.1.7 74,408 12/30/2021
0.1.7-pre000015 183 12/30/2021
0.1.7-pre000013 207 12/20/2021
0.1.7-pre000012 195 12/7/2021
0.1.6 22,069 12/7/2021
0.1.6-pre000010 202 12/6/2021
0.1.5 3,450 12/6/2021
0.1.5-pre000072 8,824 12/3/2020
0.1.5-pre000071 1,216 11/20/2020
0.1.5-pre000008 194 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,141 11/24/2021
0.1.5-pre000002 199 11/23/2021
0.1.5-pre000001 239 11/12/2021
0.1.4 109,260 11/20/2020
0.1.4-pre000066 6,480 6/17/2020
0.1.3 91,183 6/17/2020
0.1.3-pre000058 12,139 3/3/2020
0.1.3-pre000057 354 3/3/2020
0.1.2 75,220 3/3/2020
0.1.1 87,026 1/16/2020
0.1.1-pre000049 2,574 10/1/2019
0.1.1-pre000048 397 9/30/2019
0.1.1-pre000047 869 8/23/2019
0.1.1-pre000046 1,340 3/21/2019
0.1.0 96,675 3/21/2019
0.1.0-pre000044 436 3/21/2019
0.0.1-pre000043 1,058 1/16/2019
0.0.1-pre000042 1,359 9/27/2018
0.0.1-pre000041 599 9/27/2018
0.0.1-pre000040 1,479 9/14/2018
0.0.1-pre000039 635 9/14/2018
0.0.1-pre000038 822 9/13/2018
0.0.1-pre000037 648 9/13/2018
0.0.1-pre000036 647 9/12/2018
0.0.1-pre000035 611 9/12/2018
0.0.1-pre000034 636 9/12/2018
0.0.1-pre000033 624 9/12/2018
0.0.1-pre000032 638 9/12/2018
0.0.1-pre000031 708 9/10/2018
0.0.1-pre000030 728 9/7/2018
0.0.1-pre000029 661 9/7/2018
0.0.1-pre000028 667 9/7/2018
0.0.1-pre000027 682 9/7/2018
0.0.1-pre000026 652 9/7/2018
0.0.1-pre000025 629 9/4/2018
0.0.1-pre000024 624 9/4/2018
0.0.1-pre000023 684 9/4/2018
0.0.1-pre000022 679 9/4/2018
0.0.1-pre000021 621 8/30/2018
0.0.1-pre000020 602 8/30/2018
0.0.1-pre000019 644 8/30/2018
0.0.1-pre000018 619 8/30/2018
0.0.1-pre000017 608 8/30/2018
0.0.1-pre000016 660 8/30/2018
0.0.1-pre000015 757 8/26/2018
0.0.1-pre000014 733 8/24/2018
0.0.1-pre000013 721 8/24/2018
0.0.1-pre000012 677 8/23/2018
0.0.1-pre000011 660 8/23/2018
0.0.1-pre000010 659 8/22/2018
0.0.1-pre000009 834 8/21/2018
0.0.1-pre000008 765 8/21/2018
0.0.1-pre000007 750 8/20/2018
0.0.1-pre000006 1,035 8/20/2018
0.0.1-pre000005 695 8/20/2018
0.0.1-pre000004 906 8/17/2018
0.0.1-pre000003 666 8/17/2018
0.0.1-pre000002 675 8/16/2018
0.0.1-pre000001 698 8/16/2018

https://github.com/vostok/tracing.abstractions/blob/master/CHANGELOG.md