Skip to content

Commit

Permalink
Update documentation and remove unesessary configuration
Browse files Browse the repository at this point in the history
  • Loading branch information
mrproliu committed Nov 14, 2023
1 parent 1840acf commit 501d054
Show file tree
Hide file tree
Showing 6 changed files with 427 additions and 350 deletions.
79 changes: 27 additions & 52 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,27 +89,6 @@ bytes = SpanBytesEncoder.JSON_V2.encode(span);

Note: The above is just an example, most likely you'll want to use an existing tracing library like [Brave](https://github.com/openzipkin/brave)

## Storage Component
Zipkin includes a [StorageComponent](zipkin/src/main/java/zipkin2/storage/StorageComponent.java), used to store and query spans and
dependency links. This is used by the server and those making collectors, or span reporters. For this reason, storage
components have minimal dependencies, but most require Java 8+

Ex.
```java
// this won't create network connections
storage = ElasticsearchStorage.newBuilder()
.hosts(asList("http://myelastic:9200")).build();

// prepare a call
traceCall = storage.spanStore().getTrace("d3d200866a77cc59");

// execute it synchronously or asynchronously
trace = traceCall.execute();

// clean up any sessions, etc
storage.close();
```

### In-Memory
The [InMemoryStorage](zipkin-server#in-memory-storage) component is packaged in zipkin's core library. It
is neither persistent, nor viable for realistic work loads. Its purpose
Expand All @@ -129,11 +108,29 @@ Note: This store requires a [job to aggregate](https://github.com/openzipkin/zip

### Elasticsearch
The [Elasticsearch](zipkin-server#elasticsearch-storage) component uses
Elasticsearch 5+ features, but is tested against Elasticsearch 6-7.x.
Elasticsearch 6+ features, but is tested against Elasticsearch 7-8.x.

It stores the analyzed data after receiving it, supports daily indexing and storage of data,
and optimizes storage space by reducing indexes.

Note: This store requires a [spark job](https://github.com/openzipkin/zipkin-dependencies) to aggregate dependency links.

It stores spans as Zipkin v2 json so that integration with other tools is
straightforward. To help with scale, this uses a combination of custom
and manually implemented indexing.
### SQLike Datasource
Supporting relational databases, both [Elasticsearch](#elasticsearch) and similar storage systems utilize
table structures to store data content at the day level.

the following databases are supported:
1. MySQL: uses MySQL 5.x features, but is tested against MySQL 5.6.
2. PostgreSQL: used PostgreSQL 9+ features, but is tested against PostgreSQL 9.6.
3. H2: uses H2 1.4 features, but is tested against H2 1.4.199.

Note: This store requires a [spark job](https://github.com/openzipkin/zipkin-dependencies) to aggregate dependency links.

### BanyanDB
The [BanyanDB](zipkin-server#banyandb-storage-components) component uses BanyanDB 0.5.0+ features, but is tested against BanyanDB 0.5.0.

BanyanDB expected to offer better compression rates, lesser memory usage,
and less CPU consumption similar to [Elasticsearch](#elasticsearch) data capacity scenarios.

Note: This store requires a [spark job](https://github.com/openzipkin/zipkin-dependencies) to aggregate dependency links.

Expand All @@ -147,46 +144,24 @@ default. Search primarily allows the trace list screen of the UI operate.
* `GET /autocompleteValues?key=X` - Distinct values of Span.tags by key
* `GET /traces` - Traces matching a query possibly including the above criteria


When search is disabled, traces can only be retrieved by ID
(`GET /trace/{traceId}`). Disabling search is only viable when there is
(`GET /trace/{traceId}` or `GET /traceMany?traceIds=X`). Disabling search is only viable when there is
an alternative way to find trace IDs, such as logs. Disabling search can
reduce storage costs or increase write throughput.

`StorageComponent.Builder.searchEnabled(false)` is implied when a zipkin
is run with the env variable `SEARCH_ENABLED=false`.

### Legacy (v1) components
The following components are no longer encouraged, but exist to help aid
transition to supported ones. These are indicated as "v1" as they use
data layouts based on Zipkin's V1 Thrift model, as opposed to the
simpler v2 data model currently used.

#### MySQL
The [MySQL v1](zipkin-storage/mysql-v1) component uses MySQL 5.6+
features, but is tested against MariaDB 10.3.

The schema was designed to be easy to understand and get started with;
it was not designed for performance. Ex spans fields are columns, so
you can perform ad-hoc queries using SQL. However, this component has
[known performance issues](https://github.com/openzipkin/zipkin/issues/1233): queries will eventually take seconds to return
if you put a lot of data into it.

This store does not require a [job to aggregate](https://github.com/openzipkin/zipkin-dependencies) dependency links.
However, running the job will improve performance of dependencies
queries.

## Running the server from source
The [Zipkin server](zipkin-server) receives spans via HTTP POST and respond to queries
from its UI. It can also run collectors, such as RabbitMQ or Kafka.

To run the server from the currently checked out source, enter the
following. JDK 11 is required to compile the source.
```bash
# Init and update all submodule
$ git submodule update --init --recursive
# Build the server and also make its dependencies
$ ./mvnw -q --batch-mode -DskipTests --also-make -pl zipkin-server clean install
$ ./mvnw -q --batch-mode -DskipTests -Dcheckstyle.skip=true --also-make clean install
# Run the server
$ java -jar ./zipkin-server/target/zipkin-server-*exec.jar
$ java -jar ./zipkin-server/server-starter/target/zipkin-server-starter*exec.jar
```

## Artifacts
Expand Down
9 changes: 4 additions & 5 deletions docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@ We also provide [example compose files](examples/README.md) that integrate colle
such as Kafka or Elasticsearch.

## Configuration
Configuration is via environment variables, defined by [zipkin-server](https://github.com/openzipkin/zipkin/blob/master/zipkin-server/README.md). Notably, you'll want to look at the `STORAGE_TYPE` environment variables, which
include "cassandra", "mysql" and "elasticsearch".
Configuration is via environment variables, defined by [zipkin-server](https://github.com/openzipkin/zipkin/blob/master/zipkin-server/README.md). Notably, you'll want to look at the `ZIPKIN_STORAGE` environment variables, which
include "cassandra", "mysql", "h2", "postgresql", "banyandb" and "elasticsearch".

Note: the `openzipkin/zipkin-slim` image only supports "elasticsearch" storage. To use other storage types, you must use the main image `openzipkin/zipkin`.

Expand Down Expand Up @@ -69,7 +69,7 @@ For example, to increase heap size, set `JAVA_OPTS` as shown in our [docker-comp
For example, to add debug logging, set `command` as shown in our [docker-compose](examples/docker-compose.yml) file:
```yaml
command: --logging.level.zipkin2=DEBUG
command: -Dlog.level=DEBUG
```

## Runtime user
Expand All @@ -92,14 +92,13 @@ accordingly.

Ex. If your link name is "storage" for an Elasticsearch container:
```
ES_HOSTS=http://$STORAGE_PORT_9200_TCP_ADDR:9200
ZIPKIN_STORAGE_ES_CLUSTER_NODES=$STORAGE_PORT_9200_TCP_ADDR:9200
```

The above is mentioned only for historical reasons. The OpenZipkin community
do not support Docker's deprecated container links.

### MySQL
If using an external MySQL server or image, ensure schema and other parameters match the [docs](https://github.com/openzipkin/zipkin/tree/master/zipkin-storage/mysql-v1#applying-the-schema).

## Building images

Expand Down
Loading

0 comments on commit 501d054

Please sign in to comment.