swift-distributed-tracing

Instrumentation library for Swift server applications

APACHE-2.0 License

Stars
213
Committers
10
View Code on GitHub Visit Website
Ecosystems: Swift

Bot releases are hidden (Show)

swift-distributed-tracing - 1.1.1 Latest Release

Published by ktoso 5 months ago

What's Changed

New Contributors

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/1.1.0...1.1.1

swift-distributed-tracing - 1.1.0

Published by ktoso 9 months ago

Supported Swift versions

  • This release drops the support for Swift 5.6, and keeps support for 5.7, 5.8, 5.9, 5.10.

  • The legacy type LegacyTracer remains available however is now deprecated.

  • Please avoid using the deprecated "AnySpan" based APIs.

This release also cleans up some Sendability warnings in preparation for "complete concurrency checking" that will arrive in Swift 6.

What's Changed

New Contributors

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/1.0.1...1.1.0

swift-distributed-tracing - 1.0.1

Published by ktoso over 1 year ago

1.0.1

Patch release adjusting how we deal with availability annotations.

Marking availability on specific types and not on package level makes it possible to adopt entirely optionally in packages which otherwise do not require the most recent (5.6+) Swift versions.

Thank you to @adam-fowler for the patch and upcoming adoption in Hummingbird.

What's Changed

New Contributors

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/1.0.0...1.0.1

swift-distributed-tracing - 1.0.0

Published by ktoso over 1 year ago

Initial 1.0 release

After a very long period of incubation, including the development of language features (SE-0311: Task Locals) and multiple iterations on exact shapes of the API to ensure least possible impact on instrumented code when tracing is disabled, we are happy to announce the first source stable release of swift-distributed-tracing!

This package is an "API package", in the same way swift-log and swift-metrics are. This means that this package does not offer a Tracer implementation, but allows libraries to use this abstract API to instrument their code (e.g. http clients, distributed actors, gRPC or other) using tracing and once a tracer is bootstrapped by an end user, spans from given library are included in the distributed trace.

Special thanks

It should be noted that this project initially kicked off thanks to Swift participating in Google Summer of Code in 2020 (initial repository announcement), and would not have been possible without the relentless efforts of @slashmo sticking to the work and project even 3 years after GSoC concluded.

Maturing such crucial "core" libraries for the server ecosystem takes time, and we've since gained multiple Swift language features which made this library possible, and we'd like to extend our thanks to everyone involved along the way. Thanks!

Reference Documentation

Getting started with distributed tracing can be somewhat daunting, so in order to explain how to adopt and what "kind of adopter" and aspect of APIs you should be looking at, the initial release features comprehensive reference documentation in the form of docc documentation hosted on swiftpackageindex.com (or generated from the 1.0 sources).

Notable changes since beta releases

When upgrading from beta releases you might need to take care of the following changes:

  • The Baggage type, previously vended by the swift-distributed-tracing-baggage package is now known as ServiceContext and has also announced its 1.0 release.
  • It is possible to mock time using the tracing instant types
  • The library now splits its API between LegacyTracer which is Swift 5.6 compatible, and Tracer which requires Swift 5.7+
    • The reason for this is that the APIs now return a concrete Span type from startSpan which allows avoiding existential boxing if using tracers explicitly. And such return type is only supported since Swift 5.7 because the Span protocol is a "protocol with associated types"

Further, several small improvements have been made since the betas, but nothing has fundamentally changed in the APIs.

Adoption plans

We anticipate a few tracing implementations (most notably slashmo/swift-otel) to soon release 1.0 compatible versions of libraries.

We (as in the SSWG workgroup) will also collaborate with various client (e.g. http) and server projects to spread the adoption of this API in such way that enabling tracing should give a great ecosystem wide user experience. This process will take time, and we would love to see the community help with this process!

If you have any questions about implementing tracers, or adopting them in your libraries or projects please don't hesitate to reach out on the forums: https://forums.swift.org/c/server/43 or in this repository's issues.

What's Changed

New Contributors

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/0.3.1...1.0.0

swift-distributed-tracing - 1.0.0-beta.2

Published by ktoso over 1 year ago

Important notes

Please note that during the beta convergence period slight API changes are still happening.

Please have a look at some of the type renames and move away from Clock types towards a TracerInstant and adjust tracer implementations accordingly.

Important PRs changing APIs are:

In addition to that you can view the 13 closed issues on the associated milestone.

Other changes

New Contributors

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/1.0.0-beta.1...1.0.0-beta.2

swift-distributed-tracing - 1.0.0-beta.1

Published by ktoso over 1 year ago

First Beta release

Hi everyone, this is the first beta release of the tracing API.

We changed many things but believe we have arrived at the final API shapes of the library.

Most notably, it is possible to stick to concrete types if necessary, abstract away the notion of time, as well as mutate span names in-flight before they are ended.

No-op tracing also gained significant performance improvements, with NoopSpan becoming a struct and therefore not incurring reference counting traffic. And time is not going to be read unless the tracer decides to do so (allowing for no-op and inactive spans to avoid reading the system clock).

Call to action: please try out the APIs in your tracers or adoption

Please try out the APIs before we freeze them in a 1.0 release in the coming weeks.

During the beta period, we are still able to perform any breaking or important changes before this API will become frozen for the foreseeable future. Please raise your issues on the github issue tracker.

Updating from 0.3.x

There have been a number of source breaking changes in order to achieve the ideal 1.0 shape of APIs since the 0.3.x series of this library.

  • protocol Tracer became protocol TracerProtocol
    • this was in order to introduce the Tracer namespace so that we can offer Tracer.withSpan(...) { ... } rather than the too long InstrumentationSystem.tracer.withSpan(...) {
  • the startSpan protocol requirement now accepts a function and clock parameters
    • please use the clock to obtain the timestamp of the events emitted by the tracer, rather than other time sources
    • by default the DefaultTracerClock will be used
  • a new LegacyTracerProtocol is introduced which is designed specifically to support Swift 5.6 clients
    • this protocol cannot make use of returning generic Span types, and has to erase them to any Span, which is why all APIs are phrased as startAnySpan
    • this protocol will be deprecated as soon as the library is able to require Swift 5.7, however it will not be removed in order to retain source compatibility with adopters who may have been using this API for a migration period.
    • if your library adopting (or implementing) distributed tracing CAN use Swift 5.7+, please implement the TracerProtocol directly; Implementations for the Any versions of APIs will be provided for you automatically, delegating to your startSpan implementation, so you do not need to implement any of the Legacy APIs.
  • documentation updates are incoming, including full guides for implementing and using tracers here: https://github.com/apple/swift-distributed-tracing/pull/69

Swift versions

We are going to stick to the AsyncHTTP, gRPC and other core server library's Swift support strategy.

This means that this package currently will support Swift: 5.6, 5.7, 5.8, and when 5.9 is released, we will drop support for 5.6.
Supporting Swift 5.6 comes with a significant burden for this project, and we want to drop it as soon as our adopters allow us to (i.e. AsyncHTTPClient and friends).

We envision this library to be depended on by these projects and therefore must adhere to their minimum supported Swift policies.

What's Changed

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/0.3.1...1.0.0-beta.1

swift-distributed-tracing - 0.3.1

Published by ktoso about 2 years ago

Changes

  • Added withSpan overload to accept a baggage from non-async code, but have the operation closure be async
  • Prepared docc setup, though not publishing yet.

What's Changed

New Contributors

Full Changelog: https://github.com/apple/swift-distributed-tracing/compare/0.3.0...0.3.1

swift-distributed-tracing - 0.3.0

Published by ktoso over 2 years ago

Release with Sendable

swift-distributed-tracing - 0.2.0

Published by slashmo about 3 years ago

Updated:

  • LoggingContext-based propagation was replaced with automatic context propagation via task-locals (#52)
  • SpanStatus now conforms to Equatable (#46)
  • OpenTelemetryTracingSupport was removed (#53)

For details on the changes please refer to the 0.2.0 milestone

swift-distributed-tracing - 0.1.4

Published by slashmo over 3 years ago

Updated:

  • TracingOpenTelemetrySupport now includes all semantic span attributes defined in Otel (0.7.0) (#38)

Fixed:

  • Replaced all usage of sanity with soundness (#37)

For details on the changes please refer to the 0.1.4 milestone

swift-distributed-tracing - 0.1.3

Published by slashmo almost 4 years ago

Updated:

  • SpanStatus.CannonicalCode has been removed in favor of SpanStatus.Code (#31)

Fixed:

  • The context version of withSpan now delegates to the baggage version of this function (#36)
  • A "dead" link in the README file has been fixed (#35, credit to @MrCull)

For details on the changes please refer to the 0.1.3 milestone

swift-distributed-tracing - 0.1.2

Published by slashmo almost 4 years ago

Fixed:

  • When using withSpan, span.end() is now correctly called on the happy path (#33, credit to @JensAyton)

For details on the changes please refer to the 0.1.2 milestone

swift-distributed-tracing - 0.1.1

Published by ktoso almost 4 years ago

Same as 0.1.0 however fixed the dependency url in Package.swift to use https rather than git.

swift-distributed-tracing - 0.1.0

Published by ktoso almost 4 years ago

Initial release.

Package Rankings
Top 9.92% on Swiftpackageindex.com
Related Projects
swift-distributed-actors

Peer-to-peer cluster implementation for Swift Distributed Actors

23 Jul 2019 587
swiftpm-on-llbuild2

28 May 2020 39
websocket-actor-system

A client/server actor system for Swift distributed actors

31 Oct 2023 82
tracelog

TraceLog is a highly configurable, flexible, portable, and simple to use debug logging system for...

31 Oct 2015 53
Learn-iOS-Swift-by-Examples

精心收集并分类整理的Swift开发学习资源，包括Apple官方提供的示例代码和文档，以及github上的项目和国内外开发者的技术博客。欢迎提交pull-request一起维护。https://t...

03 Jun 2014 3,697
swifter

Tiny http server engine written in Swift programming language.

06 Jun 2014 3,882
swift-distributed-tracing-extras

14 Oct 2020 33
swift-tools-support-async

Common infrastructural helpers on top of NIO for llbuild2 and swiftpm-on-llbuild2 projects. This ...

13 Jun 2020 29
SwiftSimctl

Swift client-server tool to call xcrun simctl from your simulator. Automate push notification tes...

18 Mar 2020 70
live-caller-id-lookup-example

Example service & documentation for Live Caller ID Lookup

26 Jun 2024 102
awesome-system-swift

An index of cross-platform libraries or projects made in Swift by the open source community. Issu...

05 Apr 2018 104
DistributedTracer

A wrapped swift-otel tracer you can use with iOS and macOS tests

01 Apr 2024 3
swift-openapi-runtime

API package for code generated by Swift OpenAPI Generator.

20 Apr 2023 180
SwiftDSSocket

DispatchSource based socket framework written in pure Swift

31 Jul 2017 62
swift-statsd-client

metrics backend for swift-metrics that uses the statsd protocol

02 Jun 2019 58