Standards

The Jaeger library follows specific coding standards and guidelines to ensure code quality, maintainability, and consistency. These standards are outlined in the following sections:

Developer Certificate of Origin (DCO)

The Jaeger library uses the Developer Certificate of Origin 1.1 to ensure that all contributions are made with the appropriate permissions and acknowledgements. This document outlines the following three conditions:

• (a) The contribution was created in whole or in part by the contributor.
• (b) The contribution is based on previous work covered under an appropriate open source license, with modifications.
• (c) The contribution was provided directly to the contributor by another person who certified (a), (b), or (c) and has not been modified.

The DCO is available at DCO.

Project Purpose and Usage

The Jaeger library provides a collection of shared infrastructure libraries used by various Jaeger backend and client components. It is not intended for standalone use and does not provide any guarantees of backwards compatibility. Its import path is github.com/uber/jaeger-lib.

Project Dependencies

The Jaeger library depends on the following packages, specified in the Gopkg.toml file:

• github.com/go-kit/kit: 0.9.0
• github.com/HdrHistogram/hdrhistogram-go: 0.9.0
• github.com/uber-go/tally: >=2.1.0, <4.0.0
• github.com/prometheus/client_golang: 1.1.0
• github.com/stretchr/testify: 1.4.0

Code Snippets

The Jaeger library uses various code snippets to demonstrate functionality and testing. Here are some examples:

Metrics Testing:

func assertMetrics(t *testing.T, actualMetrics map[string]int64, expectedMetrics ...ExpectedMetric) {
              for _, expected := range expectedMetrics {
                  key := metrics.GetKey(expected.Name, expected.Tags, "|", "=")
                  assert.EqualValues(t,
                      expected.Value,
                      actualMetrics[key],
                      "expected metric name: %s, tags: %+v", expected.Name, expected.Tags,
                  )
              }
          }
          

Metrics Factory Interface:

// FactoryWithTags creates metrics with fully qualified name and tags.
          type FactoryWithTags interface {
              Counter(options metrics.Options) metrics.Counter
              Gauge(options metrics.Options) metrics.Gauge
              Timer(options metrics.TimerOptions) metrics.Timer
              Histogram(options metrics.HistogramOptions) metrics.Histogram
          }
          

Metrics Initialization:

// MustInit initializes the passed in metrics and initializes its fields using the passed in factory.
          //
          // It uses reflection to initialize a struct containing metrics fields
          // by assigning new Counter/Gauge/Timer values with the metric name retrieved
          // from the `metric` tag and stats tags retrieved from the `tags` tag.
          //
          // Note: all fields of the struct must be exported, have a `metric` tag, and be
          // of type Counter or Gauge or Timer.
          //
          // Errors during Init lead to a panic.
          func MustInit(metrics interface{}, factory Factory, globalTags map[string]string) {
              if err := Init(metrics, factory, globalTags); err != nil {
                  panic(err.Error())
              }
          }
          

Fork Factory Implementation:

// Gauge implements metrics.Factory interface.
          func (f *Factory) Gauge(options metrics.Options) metrics.Gauge {
              return f.defaultFactory.Gauge(options)
          }
          

Go-Kit Factory Interface:

// Factory provides a unified interface for creating named metrics
          // from various go-kit metrics implementations.
          type Factory interface {
              Counter(name string) kit.Counter
              Gauge(name string) kit.Gauge
              Histogram(name string) kit.Histogram
              Capabilities() Capabilities
          }
          

Project Documentation

The project includes various documentation resources:

• README.md: Provides an overview of the project, its dependencies, and usage instructions.
• CONTRIBUTING.md: Outlines the contribution guidelines and process for the project.
• Godoc: Offers comprehensive API documentation for the library, accessible at Godoc.

Project CI/CD

The project uses continuous integration and continuous delivery (CI/CD) to automate testing and code quality checks.

• Unit Tests: The project includes unit tests to ensure code functionality and maintainability.
• Coverage Status: The project tracks test coverage using Coveralls, with coverage information available at Coveralls.
• Build Status: The project uses Github Actions for CI/CD, with build status information available at Github Actions.

Top-Level Directory Explanations

metrics/ - This directory contains the metrics implementation for the Jaeger Tracing library.

metrics/adapters/ - This subdirectory contains the various metric adapters for different backends.

metrics/expvar/ - This subdirectory contains the implementation for exposing metrics as HTTP endpoints using the expvar package.

metrics/fork/ - This subdirectory contains the implementation for forking metrics between processes.

metrics/go-kit/ - This subdirectory contains the Go-Kit integration for the Jaeger Tracing library.

metrics/go-kit/expvar/ - This subdirectory contains the expvar implementation for the Go-Kit integration.

metrics/metricstest/ - This subdirectory contains the testing implementation for the metrics.

metrics/multi/ - This subdirectory contains the implementation for collecting metrics from multiple sources.

metrics/prometheus/ - This subdirectory contains the Prometheus implementation for the Jaeger Tracing library.

metrics/tally/ - This subdirectory contains the implementation for counting metrics using the tally package.