Improve v2 docs

content/docs/next-release-v2/cassandra.md

@@ -3,37 +3,33 @@ title: Cassandra
 hasparent: true
 ---
 
-* Supported versions: 4+
+* Supported Cassandra versions: 4.x, 5.x
 
-{{< danger >}}
-TODO update examples to use config properties, not CLI flags.
-{{< /danger >}}
-
-Deploying Cassandra itself is out of scope for our documentation. One good
-source of documentation is the [Apache Cassandra Docs](https://cassandra.apache.org/doc/latest/).
+This page describes how to configure Jaeger to use an existing Cassandra cluster as a storage backend for traces. For instructions on how to deploy a Cassandra cluster, please refer to [Apache Cassandra Documentation](https://cassandra.apache.org/doc/latest/).
 
 Cassandra also has the following officially supported resources available from the community:
 - [Docker container](https://hub.docker.com/_/cassandra) for getting a single node up quickly
 - [Helm chart](https://artifacthub.io/packages/helm/bitnami/cassandra) from Bitnami
 - [Kubernetes Operator](https://github.com/k8ssandra/cass-operator) from DataStax
 
-#### Configuration
+## Configuration
 
-Configuration example for [Jaeger writing to Cassandra](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/config-cassandra.yaml).
+A sample configuration for Jaeger with Cassandra backend is available in the Jaeger repository: [config-cassandra.yaml](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/config-cassandra.yaml). In the future the configuration documentation will be auto-generated from the schema. Meanwhile, please refer to [config.go](https://github.com/jaegertracing/jaeger/blob/main/pkg/cassandra/config/config.go#L21) as the authoritative source.
 
-#### Schema script
+## Initializing Schema
 
-A script is provided to initialize Cassandra keyspace and schema
-using Cassandra's interactive shell [`cqlsh`][cqlsh]:
+Before Jaeger can use a Cassandra cluster as storage backend, a keyspace and database schema
+must be created. There is a script in the [jaeger](https://github.com/jaegertracing/jaeger) repository that generates the initialization instruction that can be executed using Cassandra's interactive shell [`cqlsh`][cqlsh]:
 
 ```sh
 MODE=test sh ./plugin/storage/cassandra/schema/create.sh | cqlsh
 ```
 
-Or using the published Docker image (make sure to provide the right IP address):
+The same script is packaged as a container image (make sure to provide the right IP address):
 ```sh
 docker run \
   -e CQLSH_HOST={server IP address}  \
+  -e MODE=prod \
   jaegertracing/jaeger-cassandra-schema:{{< currentVersion >}}
 ```
 
@@ -43,24 +39,15 @@ where `{datacenter}` is the name used in the Cassandra configuration / network t
 The script also allows overriding TTL, keyspace name, replication factor, etc.
 Run the script without arguments to see the full list of recognized parameters.
 
-**Note**: See [README](https://github.com/jaegertracing/jaeger/blob/main/plugin/storage/cassandra/schema/README.md) for more details on Cassandra schema management.
+* **Note 1**: See [README](https://github.com/jaegertracing/jaeger/blob/main/plugin/storage/cassandra/schema/README.md) for more details on Cassandra schema management.
+* **Note 2**: In the near future the logic for schema initialization will be moved to the Jaeger binary directly (subscribe to [Issue #5797](https://github.com/jaegertracing/jaeger/issues/5797) for updates).
 
-#### TLS support
+## TLS support
 
-Jaeger supports TLS client to node connections as long as you've configured
-your Cassandra cluster correctly. After verifying with e.g. `cqlsh`, you can
-configure the collector and query like this:
+Jaeger supports TLS client-to-node connections as long as you've configured
+your Cassandra cluster correctly. You can specify paths to the TLS certificates (`.pem` files) un the `tls:` section under `connection:`. See [configtls.ClientConfig](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md#client-configuration) in the OpenTelemetry Collector repository for available properties.
 
-```sh
-docker run \
-  -e CASSANDRA_SERVERS=<...> \
-  -e CASSANDRA_TLS=true \
-  -e CASSANDRA_TLS_SERVER_NAME="CN-in-certificate" \
-  -e CASSANDRA_TLS_KEY=<path to client key file> \
-  -e CASSANDRA_TLS_CERT=<path to client cert file> \
-  -e CASSANDRA_TLS_CA=<path to your CA cert file> \
-  jaegertracing/jaeger-collector:{{< currentVersion >}}
-```
+**Tip**: verify the correctness of your TLS certificates using `cqlsh` first.
 
 The schema tool also supports TLS. You need to make a custom cqlshrc file like
 so:
@@ -86,6 +73,6 @@ usercert = ~/.cassandra/client-cert
 # validate = false
 ```
 
-#### Compatible Backends
+## Compatible Backends
 
 * ScyllaDB [can be used](https://github.com/jaegertracing/jaeger/blob/main/plugin/storage/scylladb/README.md) as a drop-in replacement for Cassandra since it uses the same data model and query language.

content/docs/next-release-v2/configuration.md

@@ -23,7 +23,7 @@ Here is an example of how to configure the extension:
 ```yaml
 jaeger_storage:
   backends:
-    some_storage:
+    some_trace_storage:
       memory:
         max_traces: 100000
   metric_backends:
@@ -48,7 +48,7 @@ In this example:
 ```yaml
 jaeger_query:
   storage:
-    traces: some_storage
+    traces: some_trace_storage
     metrics: some_metrics_storage
   base-path: /
   ui:
@@ -86,7 +86,7 @@ remote_sampling:
 
 ```yaml
 jaeger_storage_exporter:
-  trace_storage: some_store
+  trace_storage: some_trace_storage
   queue:
     num_consumers: 10
     queue_size: 100

content/docs/next-release-v2/deployment.md

@@ -31,77 +31,40 @@ See [APIs](../apis/) for the list of all API ports.
 
 Jaeger can be customized via configuration YAML file (see [Configuration](../configuration/)). 
 
-
-**jaeger** is stateless and thus many instances of **jaeger** can be run in parallel. **jaeger** instances require almost no configuration, except for storage location, such as:
-
-Cassandra:
-```
-  jaeger_storage:
-    backends:
-      some_storage:
-        cassandra:
-          schema: 
-            keyspace: "jaeger_v1_dc1"
-          connection:
-            auth: 
-              basic:
-                username: "cassandra"
-                password: "cassandra"
-            tls:
-              insecure: true
-```
-
-OpenSearch:
-```
-  jaeger_storage:
-    backends:
-      some_storage:
-        opensearch:
-          index_prefix: "jaeger-main"
-```
-
-ElasticSearch:
-```
-  jaeger_storage:
-    backends:
-      some_storage:
-        elasticsearch:
-          index_prefix: "jaeger-main"
-      another_storage:
-        elasticsearch:
-          index_prefix: "jaeger-archive"
-```
+Jaeger **collector** is stateless and thus many instances of **collector** can be run in parallel. **collector** instances require almost no configuration, except for storage location, such as [Cassandra](../cassandra/#configuration) or [Elasticsearch](../elasticsearch/#configuration).
 
 ## Query Configuration
 
-The `jaeger_query` extension has a few deployment-related configuration options.
+The `jaeger_query` extension has a few deployment-related configuration options. In the future the configuration documentation will be auto-generated from the schema. Meanwhile, please refer to [config.go](https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegerquery/config.go#L16) as the authoritative source.
 
 ### Clock Skew Adjustment
 
 Jaeger backend combines trace data from applications that are usually running on different hosts. The hardware clocks on the hosts often experience relative drift, known as the [clock skew effect](https://en.wikipedia.org/wiki/Clock_skew). Clock skew can make it difficult to reason about traces, for example, when a server span may appear to start earlier than the client span, which should not be possible. `jaeger_query` extension implements a clock skew adjustment algorithm ([code](https://github.com/jaegertracing/jaeger/blob/master/model/adjuster/clockskew.go)) to correct for clock drift, using the knowledge about causal relationships between spans. All adjusted spans have a warning displayed in the UI that provides the exact clock skew delta applied to their timestamps.
 
 Sometimes these adjustments themselves make the trace hard to understand. For example, when repositioning the server span within the bounds of its parent span, Jaeger does not know the exact relationship between the request and response latencies, so it assumes they are equal and places the child span in the middle of the parent span (see [issue #961](https://github.com/jaegertracing/jaeger/issues/961#issuecomment-453925244)).
 
-**jaeger** query extension supports configuration in the config file
+The `jaeger_query` extension supports a configuration property that controls how much clock skew adjustment should be allowed.
 
 ```
-query:
-  max-clock-skew-adjustment: 30s
+extensions:
+  jaeger_query:
+    max-clock-skew-adjustment: 30s
 ```
 
- that controls how much clock skew adjustment should be allowed. Setting this parameter to zero (`0s`) disables clock skew adjustment completely. This setting applies to all traces retrieved from the given query service. There is an open [ticket #197](https://github.com/jaegertracing/jaeger-ui/issues/197) to support toggling the adjustment on and off directly in the UI.
+ Setting this parameter to zero (`0s`) disables clock skew adjustment completely. This setting applies to all traces retrieved from the given query service. There is an open [ticket #197](https://github.com/jaegertracing/jaeger-ui/issues/197) to support toggling the adjustment on and off directly in the UI.
 
 ### UI Base Path
 
-The base path for all **jaeger** query extension HTTP routes can be set to a non-root value, e.g. `/jaeger` would cause all UI URLs to start with `/jaeger`. This can be useful when running **jaeger** behind a reverse proxy. Here is example code to set the base path.
+The base path for all `jaeger_query` extension HTTP routes can be set to a non-root value, e.g. `/jaeger` would cause all UI URLs to start with `/jaeger`. This can be useful when running Jaeger behind a reverse proxy. Here is example code to set the base path.
 
 ```
-query:
-  base-path: /
-  static-files: /go/bin/jaeger-ui-build/build
-  ui-config: /etc/jaeger/ui-config.json
-  grpc:
-  http:
+extensions:
+  jaeger_query:
+    base-path: /
+    ui:
+      config_file: /etc/jaeger/ui-config.json
+    grpc:
+    http:
 ```
 
 ### UI Customization and Embedding