Release release-1.54.0 (#673)

Release release-1.54.0. This PR is created from CI and is part of the
release process.

Signed-off-by: jaegertracingbot <jaegertracingbot+jaeger-tracing@googlegroups.com>
Co-authored-by: jaegertracingbot <jaegertracingbot+jaeger-tracing@googlegroups.com>

config.toml

@@ -25,9 +25,9 @@ home = [ "HTML", "JSON", "REDIRECTS" ]
   mediumhandle   = "jaegertracing"
   opengraphimage = "img/jaeger-icon-color.png"
 
-  latest = "1.53"
-  binariesLatest = "1.53.0"
-  versions = ["1.53","1.52","1.51","1.50","1.49","1.48","1.47","1.46","1.45","1.44","1.43","1.42","1.41","1.40","1.39","1.38","1.37","1.36","1.35","1.34","1.33","1.32"]
+  latest = "1.54"
+  binariesLatest = "1.54.0"
+  versions = ["1.54","1.53","1.52","1.51","1.50","1.49","1.48","1.47","1.46","1.45","1.44","1.43","1.42","1.41","1.40","1.39","1.38","1.37","1.36","1.35","1.34","1.33","1.32"]
 
   [navbar]
     [[links]]

content/docs/1.54/_index.md

@@ -0,0 +1,77 @@
+---
+title: Introduction
+weight: 1
+children:
+- title: Features
+  url: features
+---
+
+Welcome to Jaeger's documentation portal! Below, you'll find information for beginners and experienced Jaeger users.
+
+If you cannot find what you are looking for, or have an issue not covered here, we'd love to [hear from you](/get-in-touch).
+
+If you are new to distributed tracing, please take a look at the [Related Links](#related-links) section below.
+
+## About
+
+Jaeger is a distributed tracing platform released as open source by [Uber Technologies][ubeross].
+With Jaeger you can:
+
+* Monitor and troubleshoot distributed workflows
+* Identify performance bottlenecks
+* Track down root causes
+* Analyze service dependencies
+
+Uber published a blog post, [Evolving Distributed Tracing at Uber](https://eng.uber.com/distributed-tracing/), where they explain the history and reasons for the architectural choices made in Jaeger. [Yuri Shkuro](https://shkuro.com), creator of Jaeger, also published a book [Mastering Distributed Tracing](https://shkuro.com/books/2019-mastering-distributed-tracing/) that covers in-depth many aspects of Jaeger design and operation, as well as distributed tracing in general.
+
+## Features
+
+  * [OpenTracing](https://opentracing.io/)-inspired data model
+  * [OpenTelemetry](https://opentelemetry.io/) compatible
+  * Multiple built-in storage backends: Cassandra, Elasticsearch, in-memory
+  * Community supported external storage backends via gRPC plugin: [ClickHouse](https://github.com/jaegertracing/jaeger-clickhouse)
+  * System topology graphs
+  * Adaptive sampling
+  * Service Performance Monitoring (SPM)
+  * Post-collection data processing
+
+See [Features](./features/) page for more details.
+
+## Technical Specs
+
+  * Backend components implemented in Go
+  * React/Javascript UI
+  * Supported storage backends:
+    * [Cassandra 3.4+](./deployment/#cassandra)
+    * [Elasticsearch 5.x, 6.x, 7.x](./deployment/#elasticsearch)
+    * [Kafka](./deployment/#kafka)
+    * memory storage
+    * certified grpc-plugins:
+      * [ClickHouse](./deployment/#sidecar-model)
+
+## Quick Start
+See [Getting Started](./getting-started).
+
+## Screenshots
+
+### Traces View
+[![Traces View](/img/traces-ss.png)](/img/traces-ss.png)
+
+### Trace Detail View
+[![Detail View](/img/trace-detail-ss.png)](/img/trace-detail-ss.png)
+
+### Service Performance Monitoring View
+![Service Performance Monitoring](/img/frontend-ui/spm.png)
+
+## Related links
+- [Take Jaeger for a HotROD ride](https://medium.com/jaegertracing/take-jaeger-for-a-hotrod-ride-233cf43e46c2) (blog)
+- [Evolving Distributed tracing At Uber Engineering](https://eng.uber.com/distributed-tracing/) (blog)
+- [Mastering Distributed Tracing](https://shkuro.com/books/2019-mastering-distributed-tracing/) (book)
+- [OpenTracing Tutorial (Java, Go, Python, Node.js, C#)](https://github.com/yurishkuro/opentracing-tutorial/) (tutorials)
+- [Learning Distributed Tracing 101](https://tracing.cloudnative101.dev/docs/index.html) (tutorials)
+- [Tracing HTTP request latency in Go with OpenTracing](https://medium.com/opentracing/tracing-http-request-latency-in-go-with-opentracing-7cc1282a100a) (blog)
+- [Distributed Tracing with Jaeger & Prometheus on Kubernetes](https://blog.openshift.com/openshift-commons-briefing-82-distributed-tracing-with-jaeger-prometheus-on-kubernetes/) (blog)
+- [Using Jaeger with Istio](https://istio.io/latest/docs/tasks/observability/distributed-tracing/jaeger/) (docs)
+- [Using Jaeger with Envoy](https://www.envoyproxy.io/docs/envoy/latest/start/sandboxes/jaeger_tracing.html) (docs)
+
+[ubeross]: http://uber.github.io

content/docs/1.54/apis.md

@@ -0,0 +1,144 @@
+---
+title: APIs
+hasparent: true
+---
+
+Jaeger components implement various APIs for saving or retrieving trace data.
+
+The following labels are used to describe API compatibility guarantees.
+
+* **stable** - the API guarantees backwards compatibility. If breaking changes are going to be made in the future, they will result in a new API version, e.g. `/api/v2` URL prefix or a different namespace in the IDL.
+* **internal** - the APIs intended for internal communications between Jaeger components and not recommended for use by external components.
+* **deprecated** - the APIs that are only maintained for legacy reasons and will be phased out in the future.
+
+Since Jaeger v1.32, **jaeger-collector** and **jaeger-query** Service ports that serve gRPC endpoints enable [gRPC reflection][grpc-reflection]. Unfortunately, the internally used `gogo/protobuf` has a [compatibility issue][gogo-reflection] with the official `golang/protobuf`, and as a result only the `list` reflection command is currently working properly.
+
+## Span reporting APIs
+
+**jaeger-agent** and **jaeger-collector** are the two components of the Jaeger backend that can receive spans. At this time they support two sets of non-overlapping APIs.
+
+### OpenTelemetry Protocol (stable)
+
+Since v1.35, the Jaeger backend can receive trace data from the OpenTelemetry SDKs in their native [OpenTelemetry Protocol (OTLP)][otlp]. It is no longer necessary to configure the OpenTelemetry SDKs with Jaeger exporters, nor deploy the OpenTelemetry Collector between the OpenTelemetry SDKs and the Jaeger backend.
+
+The OTLP data is accepted in these formats: (1) binary gRPC, (2) Protobuf over HTTP, (3) JSON over HTTP. For more details on the OTLP receiver see the [official documentation][otlp-rcvr]. Note that not all configuration options are supported in **jaeger-collector** (see `--collector.otlp.*` [CLI Flags](../cli/#jaeger-collector)), and only tracing data is accepted, since Jaeger does not store other telemetry types.
+
+| Port  | Protocol | Endpoint     | Format
+| ----- | -------  | ------------ | ----
+| 4317  | gRPC     | n/a          | Protobuf
+| 4318  | HTTP     | `/v1/traces` | Protobuf or JSON
+
+[otlp-rcvr]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/receiver/otlpreceiver/README.md
+[otlp]: https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md
+
+### Thrift over UDP (stable)
+
+**jaeger-agent** can only receive spans over UDP in Thrift format. The primary API is a UDP packet that contains a Thrift-encoded `Batch` struct defined in [jaeger.thrift] IDL file, located in the [jaeger-idl] repository. Most Jaeger Clients use Thrift's `compact` encoding, however some client libraries do not support it (notably, Node.js) and use Thrift's `binary` encoding (sent to  a different UDP port). **jaeger-agent**'s API is defined by [agent.thrift] IDL file.
+
+For legacy reasons, **jaeger-agent** also accepts spans over UDP in Zipkin format, however, only very old versions of Jaeger clients can send data in that format and it is officially deprecated.
+
+### Protobuf via gRPC (stable)
+
+In a typical Jaeger deployment, **jaeger-agent**s receive spans from Clients and forward them to **jaeger-collector**s. Since Jaeger v1.11 the official and recommended protocol between **jaeger-agent**s and **jaeger-collector**s is `jaeger.api_v2.CollectorService` gRPC endpoint defined in [collector.proto] IDL file. The same endpoint can be used to submit trace data from SDKs directly to **jaeger-collector**.
+
+### Thrift over HTTP (stable)
+
+In some cases it is not feasible to deploy **jaeger-agent** next to the application, for example, when the application code is running as a serverless function. In these scenarios the SDKs can be configured to submit spans directly to **jaeger-collector**s over HTTP/HTTPS.
+
+The same [jaeger.thrift] payload can be submitted in HTTP POST request to `/api/traces` endpoint, for example, `https://jaeger-collector:14268/api/traces`. The `Batch` struct needs to be encoded using Thrift's `binary` encoding, and the HTTP request should specify the content type header:
+
+```
+Content-Type: application/vnd.apache.thrift.binary
+```
+
+### JSON over HTTP (n/a)
+
+There is no official Jaeger JSON format that can be accepted by **jaeger-collector**.
+Jaeger does accept the OpenTelemetry protocol via JSON (see [above](#opentelemetry-protocol-stable)).
+
+### Zipkin Formats (stable)
+
+**jaeger-collector** can also accept spans in several Zipkin data format, namely JSON v1/v2 and Thrift. **jaeger-collector** needs to be configured to enable Zipkin HTTP server, e.g. on port 9411 used by Zipkin collectors. The server enables two endpoints that expect POST requests:
+
+* `/api/v1/spans` for submitting spans in Zipkin JSON v1 or Zipkin Thrift format.
+* `/api/v2/spans` for submitting spans in Zipkin JSON v2.
+
+## Trace retrieval APIs
+
+Traces saved in the storage can be retrieved by calling **jaeger-query** Service.
+
+### gRPC/Protobuf (stable)
+
+The recommended way for programmatically retrieving traces and other data is via `jaeger.api_v2.QueryService` gRPC endpoint defined in [query.proto] IDL file. In the default configuration this endpoint is accessible from `jaeger-query:16685`.
+
+### HTTP JSON (internal)
+
+Jaeger UI communicates with **jaeger-query** Service via JSON API. For example, a trace can be retrieved via GET request to `https://jaeger-query:16686/api/traces/{trace-id-hex-string}`. This JSON API is intentionally undocumented and subject to change.
+
+## Remote Storage API (stable)
+
+When using the `grpc-plugin` storage type (a.k.a. [storage plugin](../deployment/#storage-plugin)), Jaeger components can use custom storage backends as long as those backends implement the gRPC [Remote Storage API][storage.proto].
+
+## Remote Sampling Configuration (stable)
+
+This API supports Jaeger's [Remote Sampling](../sampling/#remote-sampling) protocol, defined in [sampling.proto] IDL file.
+
+Both **jaeger-agent** and **jaeger-collector** implement the API. See [Remote Sampling](../sampling/#remote-sampling) for details on how to configure the Collector with sampling strategies. **jaeger-agent** is merely acting as a proxy to **jaeger-collector**.
+
+The following table lists different endpoints and formats that can be used to query for sampling strategies. The official HTTP/JSON endpoints use standard [Protobuf-to-JSON mapping](https://developers.google.com/protocol-buffers/docs/proto3#json).
+
+Component | Port  | Endpoint          | Format    | Notes
+--------- | ----- | ----------------- | --------- | -----
+Collector | 14268 | `/api/sampling`   | HTTP/JSON | Recommended for most SDKs
+Collector | 14250 | [sampling.proto]  | gRPC      | For SDKs that want to use gRPC (e.g. OpenTelemetry Java SDK)
+Agent     | 5778  | `/sampling`       | HTTP/JSON | Recommended for most SDKs if the Agent is used in a deployment
+Agent     | 5778  | `/` (deprecated)  | HTTP/JSON | Legacy format, with enums encoded as numbers. **Not recommended.**
+
+**Examples**
+
+Run all-in-one in one terminal:
+```shell
+$ go run ./cmd/all-in-one \
+  --sampling.strategies-file=cmd/all-in-one/sampling_strategies.json
+```
+
+Query different endpoints in another terminal:
+```shell
+# Collector
+$ curl "http://localhost:14268/api/sampling?service=foo"
+{"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":1}}
+
+# Agent
+$ curl "http://localhost:5778/sampling?service=foo"
+{"strategyType":"PROBABILISTIC","probabilisticSampling":{"samplingRate":1}}
+
+# Agent, legacy endpoint / (not recommended)
+$ curl "http://localhost:5778/?service=foo"
+{"strategyType":0,"probabilisticSampling":{"samplingRate":1}}
+```
+
+## Service dependencies graph (internal)
+
+Can be retrieved from**jaeger-query** Service at `/api/dependencies` endpoint. The GET request expects two parameters:
+
+* `endTs` (number of milliseconds since epoch) - the end of the time interval
+* `lookback` (in milliseconds) - the length the time interval (i.e. start-time + lookback = end-time).
+
+The returned JSON is a list of edges represented as tuples `(caller, callee, count)`.
+
+For programmatic access to service graph, the recommended API is gRPC/Protobuf described above.
+
+## Service Performance Monitoring (internal)
+
+Please refer to the [SPM Documentation](../spm#api)
+
+[jaeger-idl]: https://github.com/jaegertracing/jaeger-idl/
+[jaeger.thrift]: https://github.com/jaegertracing/jaeger-idl/blob/main/thrift/jaeger.thrift
+[agent.thrift]: https://github.com/jaegertracing/jaeger-idl/blob/main/thrift/agent.thrift
+[sampling.thrift]: https://github.com/jaegertracing/jaeger-idl/blob/main/thrift/sampling.thrift
+[collector.proto]: https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/collector.proto
+[query.proto]: https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/query.proto
+[sampling.proto]: https://github.com/jaegertracing/jaeger-idl/blob/main/proto/api_v2/sampling.proto
+[grpc-reflection]: https://github.com/grpc/grpc-go/blob/master/Documentation/server-reflection-tutorial.md#enable-server-reflection
+[gogo-reflection]: https://jbrandhorst.com/post/gogoproto/#reflection
+[storage.proto]: https://github.com/jaegertracing/jaeger/blob/main/plugin/storage/grpc/proto/storage.proto