opentelemetry-swift

About

The repository contains the Swift OpenTelemetry client

Getting Started

This package includes several libraries. The OpenTelemetryApi library includes protocols and no-op implementations that comprise the OpenTelemetry API following the specification. The OpenTelemetrySdk library is the reference implementation of the API.

Libraries that produce telemetry data should only depend on OpenTelemetryApi, and defer the choice of the SDK to the application developer. Applications may depend on OpenTelemetrySdk or another package that implements the API.

Adding the dependency

opentelemetry-swift is designed for Swift 5. To depend on the opentelemetry-swift package, you need to declare your dependency in your Package.swift:

.package(url: "https://github.com/open-telemetry/opentelemetry-swift", from: "1.0.0"),

and to your application/library target, add OpenTelemetryApi or OpenTelemetrySdkto your dependencies, e.g. like this:

.target(name: "ExampleTelemetryProducerApp", dependencies: ["OpenTelemetryApi"]),

or

.target(name: "ExampleApp", dependencies: ["OpenTelemetrySdk"]),

Cocoapods

As of version 1.11.0, OpenTelemetry-Swift support cocoapods. Two pods are provided:

• OpenTelemetry-Swift-Api

• OpenTelemetry-Swift-Sdk

OpenTelemetry-Swift-Api is a dependency of OpenTelemetry-Swift-Sdk.

Most users will want to add the following to their pod file:

pod 'OpenTelemetry-Swift-Sdk'

This will add both the API and SDK. If you're only interesting in Adding the API add the following:

pod 'OpenTelemetry-Swift-Api'

Documentation

Official documentation for the library can be found in the official opentelemetry documentation page, including:

• Documentation about installation and manual instrumentation

• Libraries that provide automatic instrumentation

Current status

API and SDK

Tracing and Baggage are considered stable

Logs are considered stable.

Metrics is considered stable.

Contributing

We'd love your help! Use labels and to get started with the project. For an overview of how to contribute, see the contributing guide in CONTRIBUTING.md.

We have a weekly SIG meeting! See the community page for meeting details and notes.

We are also available in the #otel-swift channel in the CNCF slack. Please join us there for OTel Swift discussions.

Release process

This project uses github releases to track release versions. Cocoapods are also deployed using the automated release process. Github actions are used to streamline the release project and generate tags and release notes with minimal intervention. The Release process has several phases:

1. Preparation
2. Framework Release Github action
3. On Release PR Merge
4. Tag & Release notes

Preparation

When it is deemed appropriate by the project maintainers to create a release a few preparations should be accounted for:

• Are all relevant PRs merged into main?
• What version number is appropriate? e.g.: is this a hotfix, minor, or major release?
• Are all dependencies in the Package.swift using appropriate version numbers? (no branches in dependency defintion)

This isn't a complete list, so use your best instincts.

Framework Release Github action

Once preparations are complete, run the Framework Release Github action. This job takes the version you selected and creates a PR updating all the necessary version locations, such as the sdk.telemetry.version, docs, and Cocoapod podspecs. This release PR needs to be manually merged and reviewed.

An additional job will also be run in the background adding a WARNING to the release PR indicating subsequent jobs will automatically be triggered after merge. This job detects the Release PR based of the branch name, and will show up if you use that naming scheme in any PR, so watchout for it.

Note: The Framework Release job should always be run on the main branch.

On Release PR merged

Once the release PR is merged an automated job is kicked off: Tag and Release

This job will run once the release PR is merged, based off the format of the PR branch name. It will auto generate a Github release, as well as push all Cocoapod specs to the Cocoapods Trunk.

Tag & Release notes

The release will be set as pre-release which allows maintainers to edit the auto-generated release notes into the appropriate format and provides a final go/no-go allowance for the release. The notes should be formatted into categories based on area of concern : e.g.: Trace, Metrics, Instrumentation.

Look to older releases for inspriation.

Maintainers (@open-telemetry/swift-core-maintainers)

• Ariel Demarco, Embrace
• Bryce Buchanan, Elastic
• Ignacio Bonafonte, Independent

For more information about the maintainer role, see the community repository.

Approvers (@open-telemetry/swift-core-approvers)

• Austin Emmons, Embrace
• Vinod Vydier, Independent

For more information about the approver role, see the community repository.

Triager (@open-telemetry/swift-core-triagers)

• Alolita Sharma, Apple
• Billy Zhou, AWS

For more information about the triager role, see the community repository.