Testing
The jaeger-lib library is extensively tested using the testify testing framework.
Unit Tests: The codebase includes a comprehensive set of unit tests that cover various aspects of the library’s functionality. These tests ensure the correctness and reliability of individual components.
Example:
func TestInitMetricsFailures(t *testing.T) { assert.EqualError(t, metrics.Init(&noMetricTag, nil, nil), "Field NoMetricTag is missing a tag 'metric'") assert.EqualError(t, metrics.Init(&badTags, nil, nil), "Field [BadTags]: Tag [noValue] is not of the form key=value in 'tags' string [1=one,noValue]") assert.EqualError(t, metrics.Init(&invalidMetricType, nil, nil), "Field InvalidMetricType is not a pointer to timer, gauge, or counter") assert.EqualError(t, metrics.Init(&badHistogramBucket, nil, nil), "Field [BadHistogramBucket]: Bucket [a] could not be converted to float64 in 'buckets' string [1,2,a,4]") assert.EqualError(t, metrics.Init(&badTimerBucket, nil, nil), "Field [BadTimerBucket]: Buckets are not currently initialized for timer metrics") assert.EqualError(t, metrics.Init(&invalidBuckets, nil, nil), "Field [InvalidBuckets]: Buckets should only be defined for Timer and Histogram metric types") }Source: metrics/metrics_test.go
Integration Tests: The library also features integration tests that verify the interaction between different components. These tests ensure the library works as expected in a real-world scenario.
Example:
func TestInitMetrics(t *testing.T) { testMetrics := struct { Gauge metrics.Gauge `metric:"gauge" tags:"1=one,2=two"` Counter metrics.Counter `metric:"counter"` Timer metrics.Timer `metric:"timer"` Histogram metrics.Histogram `metric:"histogram" buckets:"20,40,60,80"` }{} f := metricstest.NewFactory(0) defer f.Stop() globalTags := map[string]string{"key": "value"} err := metrics.Init(&testMetrics, f, globalTags) assert.NoError(t, err) testMetrics.Gauge.Update(10) testMetrics.Counter.Inc(5) testMetrics.Timer.Record(time.Duration(time.Second * 35)) testMetrics.Histogram.Record(42) // wait for metrics for i := 0; i < 1000; i++ { c, _ := f.Snapshot() if _, ok := c["counter"]; ok { break } time.Sleep(1 * time.Millisecond) } c, g := f.Snapshot() assert.EqualValues(t, 5, c["counter|key=value"]) assert.EqualValues(t, 10, g["gauge|1=one|2=two|key=value"]) assert.EqualValues(t, 36863, g["timer|key=value.P50"]) assert.EqualValues(t, 43, g["histogram|key=value.P50"]) stopwatch := metrics.StartStopwatch(testMetrics.Timer) stopwatch.Stop() assert.True(t, 0 < stopwatch.ElapsedTime()) }Source: metrics/metrics_test.go
Coverage Reports: Coverage reports are generated for each test run, providing insights into the code coverage achieved by the tests. These reports are available on the project’s coverage page.
Debugging
- Logging: The library utilizes logging to provide informative messages during execution. Use the standard Go
logpackage for debugging. - Metrics: Jaeger-lib uses Jaeger-specific metrics and exporters to provide visibility into the library’s behavior. The
jaeger-libmetrics API is used for interacting with metrics. - Debugging Tools: Utilize standard debugging tools like
GDBorDelvefor inspecting the code and stepping through execution.
Code Conventions
- Go Conventions: The library adheres to standard Go conventions for code formatting and structure.
- DCO: The library uses the Developer Certificate of Origin for contributing code. Ensure your contribution complies with the DCO guidelines.
## Top-Level Directory Explanations
<a class='local-link directory-link' data-ref="client/" href="#client/">client/</a> - This directory contains the client-side code for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="client/log/" href="#client/log/">client/log/</a> - This subdirectory contains the logging implementation for the client-side code.
<a class='local-link directory-link' data-ref="client/log/go-kit/" href="#client/log/go-kit/">client/log/go-kit/</a> - This subdirectory of the logging implementation contains the Go-Kit logging adapter.
<a class='local-link directory-link' data-ref="metrics/" href="#metrics/">metrics/</a> - This directory contains the metrics implementation for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="metrics/adapters/" href="#metrics/adapters/">metrics/adapters/</a> - This subdirectory contains the various metric adapters for different backends.
<a class='local-link directory-link' data-ref="metrics/expvar/" href="#metrics/expvar/">metrics/expvar/</a> - This subdirectory contains the implementation for exposing metrics as HTTP endpoints using the expvar package.
<a class='local-link directory-link' data-ref="metrics/fork/" href="#metrics/fork/">metrics/fork/</a> - This subdirectory contains the implementation for forking metrics between processes.
<a class='local-link directory-link' data-ref="metrics/go-kit/" href="#metrics/go-kit/">metrics/go-kit/</a> - This subdirectory contains the Go-Kit integration for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="metrics/go-kit/expvar/" href="#metrics/go-kit/expvar/">metrics/go-kit/expvar/</a> - This subdirectory contains the expvar implementation for the Go-Kit integration.
<a class='local-link directory-link' data-ref="metrics/go-kit/influx/" href="#metrics/go-kit/influx/">metrics/go-kit/influx/</a> - This subdirectory contains the InfluxDB implementation for the Go-Kit integration.
<a class='local-link directory-link' data-ref="metrics/metricstest/" href="#metrics/metricstest/">metrics/metricstest/</a> - This subdirectory contains the testing implementation for the metrics.
<a class='local-link directory-link' data-ref="metrics/multi/" href="#metrics/multi/">metrics/multi/</a> - This subdirectory contains the implementation for collecting metrics from multiple sources.
<a class='local-link directory-link' data-ref="metrics/prometheus/" href="#metrics/prometheus/">metrics/prometheus/</a> - This subdirectory contains the Prometheus implementation for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="metrics/tally/" href="#metrics/tally/">metrics/tally/</a> - This subdirectory contains the implementation for counting metrics using the tally package.
<a class='local-link directory-link' data-ref="sample/" href="#sample/">sample/</a> - This directory contains a sample implementation for the Jaeger Tracing library.
<a class='local-link directory-link' data-ref="scripts/" href="#scripts/">scripts/</a> - This directory contains various scripts for the project.
<a class='local-link directory-link' data-ref="utils/" href="#utils/">utils/</a> - This directory contains various utility functions for the project.
