<commit_before># zipkin-server
Zipkin Server is a Java 1.8+ service, packaged as an executable jar.

Span storage and collectors are [configurable](#configuration). By default, storage is in-memory,
the HTTP collector (POST /api/v2/spans endpoint) is enabled, and the server listens on port 9411.

Zipkin Server is implemented with [Armeria](https://github.com/line/armeria). While it uses [Spring Boot](http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/)
internally, Zipkin Server should not be considered a normal Spring Boot application.

## Custom servers are not supported

By Custom servers we mean trying to use/embed `zipkin` as part of _an application you package_ (e.g. adding `zipkin-server` dependency to a Spring-boot application) instead of the packaged application we release.

For proper usage, see the guides below.

## Quick-start

The quickest way to get started is to fetch the [latest released server](https://search.maven.org/remote_content?g=io.zipkin&a=zipkin-server&v=LATEST&c=exec) as a self-contained executable jar. Note that the Zipkin server requires minimum JRE 8. For example:

```bash
$ curl -sSL https://zipkin.io/quickstart.sh | bash -s
$ java -jar zipkin.jar
```

Once you've started, browse to http://your_host:9411 to find traces!

## Endpoints

The following endpoints are defined under the base url http://your_host:9411
* / - [UI](../zipkin-ui)
* /config.json - [Configuration for the UI](#configuration-for-the-ui)
* /api/v2 - [API](https://zipkin.io/zipkin-api/#/)
* /health - Returns 200 status if OK
* /info - Provides the version of the running instance
* /metrics - Includes collector metrics broken down by transport type
* /prometheus - Prometheus scrape endpoint

The [legacy /api/v1 API](https://zipkin.io/zipkin-api/#/) is still supported. Backends are decoupled from the
HTTP API via data conversion. This means you can still accept legacy data on new backends and visa versa. Enter
`https://zipkin.io/zipkin-api/zipkin-api.yaml` into the explore box of the Swagger UI to view the old definition

### CORS (Cross-origin Resource Sharing)

By default, all endpoints under `/api/v2` are configured to **allow** cross-origin requests.

This can be changed by modifying the property `zipkin.query.allowed-origins`.

For example, to allow CORS requests from `http://foo.bar.com`:

```
ZIPKIN_QUERY_ALLOWED_ORIGINS=http://foo.bar.com
```

See [Configuration](#configuration) for more about how Zipkin is configured.

### Service and Span names query
The [Zipkin API](https://zipkin.io/zipkin-api/#/default/get_services) does not include
a parameter for how far back to look for service or span names. In order
to prevent excessive load, service and span name queries are limited by
`QUERY_LOOKBACK`, which defaults to 24hrs (two daily buckets: one for
today and one for yesterday)

## Logging

By default, zipkin writes log messages to the console at INFO level and above. You can adjust
categories using the `logging.level.XXX` property.

For example, if you want to enable debug logging for all zipkin categories, you can start the server like so:

```bash
$ java -jar zipkin.jar --logging.level.zipkin2=DEBUG
```

See [Configuration](#configuration) for more about how Zipkin is configured.

### Advanced Logging Configuration
Under the covers, the server uses [Spring Boot - Logback integration](http://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html#howto-configure-logback-for-logging).
For example, you can add `--logging.exception-conversion-word=%wEx{full}` to dump full stack traces
instead of truncated ones.

## Metrics

Collector Metrics are exported to the path `/metrics`. These and additional metrics are exported
to the path `/prometheus`.

### Example Prometheus configuration
Here's an example `/prometheus` configuration, using the Prometheus
exposition [text format version 0.0.4](https://prometheus.io/docs/instrumenting/exposition_formats/)

```yaml
  - job_name: 'zipkin'
    scrape_interval: 5s
    metrics_path: '/prometheus'
    static_configs:
      - targets: ['localhost:9411']
    metric_relabel_configs:
      # Response code count
      - source_labels: [__name__]
        regex: '^status_(\d+)_(.*)$'
        replacement: '${1}'
        target_label: status
      - source_labels: [__name__]
        regex: '^status_(\d+)_(.*)$'
        replacement: '${2}'
        target_label: path
      - source_labels: [__name__]
        regex: '^status_(\d+)_(.*)$'
        replacement: 'http_requests_total'
        target_label: __name__
```

### Collector

Collector metrics are broken down by transport. The following are exported to the "/metrics" endpoint:

Metric | Description
--- | ---
counter.zipkin_collector.messages.$transport | cumulative messages received; should relate to messages reported by instrumented apps
counter.zipkin_collector.messages_dropped.$transport | cumulative messages dropped; reasons include client disconnects or malformed content
counter.zipkin_collector.bytes.$transport | cumulative message bytes
counter.zipkin_collector.spans.$transport | cumulative spans read; should relate to messages reported by instrumented apps
counter.zipkin_collector.spans_dropped.$transport | cumulative spans dropped; reasons include sampling or storage failures
gauge.zipkin_collector.message_spans.$transport | last count of spans in a message
gauge.zipkin_collector.message_bytes.$transport | last count of bytes in a message

## Configuration
We support ENV variable configuration, such as `STORAGE_TYPE=cassandra3`, as they are familiar to
administrators and easy to use in runtime environments such as Docker.

Here are the top-level configuration of Zipkin:
* `QUERY_PORT`: Listen port for the HTTP API and web UI; Defaults to 9411
* `QUERY_ENABLED`: `false` disables the HTTP read endpoints under '/api/v2'. This also disables the
UI, as it relies on the API. If your only goal is to restrict search, use `SEARCH_ENABLED` instead.
Defaults to true
* `SEARCH_ENABLED`: `false` disables searching in the query API and any indexing or post-processing
in the collector to support search. This does not disable the entire UI, as trace by ID and
dependency queries still operate. Disable this when you use another service (such as logs) to find
trace IDs. Defaults to true
* `QUERY_TIMEOUT`: Sets the hard timeout for query requests. Accepts any duration string (e.g., 100ms).
A value of 0 will disable the timeout completely. Defaults to 11s.
* `QUERY_LOG_LEVEL`: Log level written to the console; Defaults to INFO
* `QUERY_LOOKBACK`: How many milliseconds queries can look back from endTs; Defaults to 24 hours (two daily buckets: one for today and one for yesterday)
* `STORAGE_TYPE`: SpanStore implementation: one of `mem`, `mysql`, `cassandra`, `elasticsearch`
* `COLLECTOR_SAMPLE_RATE`: Percentage of traces to retain, defaults to always sample (1.0).
* `AUTOCOMPLETE_KEYS`: list of span tag keys which will be returned by the `/api/v2/autocompleteTags` endpoint; Tag keys should be comma separated e.g. "instance_id,user_id,env"
* `AUTOCOMPLETE_TTL`: How long in milliseconds to suppress calls to write the same autocomplete key/value pair. Default 3600000 (1 hr)

### Configuration file overrides
Under the scenes, all configuration are managed by Spring Boot. This means that properties may also
be overridden by system properties or any other alternative [supported by Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).

We use [yaml configuration](src/main/resources/zipkin-server-shared.yml) to bind shorter or more
idiomatic ENV variables to the Spring properties ultimately in use. While most users should only use
environment variables, some may desire a properties file approach to override settings. For example,
knowing we set `spring.config.name=zipkin-server`, Spring Boot will automatically look for a file
named `zipkin-server.properties` in the current directory, and the same properties we set in yaml
can be overridden that way.

If you choose to use property-based configuration instead of ENV variables, you are choosing to
self-support your configuration. This means you'll use [Spring Boot documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html)
or [StackOverflow](https://stackoverflow.com/questions/tagged/spring-boot) to resolve concerns
related to property resolution as opposed to raising issues or using our chat support. We have to
mention this because configuration of Spring implies vast responsibility and our resources must be
conserved for Zipkin related tasks.

## UI
Zipkin has a web UI, automatically included in the exec jar, and is hosted by default on port 9411.

When the UI loads, it reads default configuration from the `/config.json` endpoint.
<commit_msg>this parameter was never documented, fixes #718 (#3053)<commit_after># zipkin-server
Zipkin Server is a Java 1.8+ service, packaged as an executable jar.

Span storage and collectors are [configurable](#configuration). By default, storage is in-memory,
the HTTP collector (POST /api/v2/spans endpoint) is enabled, and the server listens on port 9411.

Zipkin Server is implemented with [Armeria](https://github.com/line/armeria). While it uses [Spring Boot](http://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/)
internally, Zipkin Server should not be considered a normal Spring Boot application.

## Custom servers are not supported

By Custom servers we mean trying to use/embed `zipkin` as part of _an application you package_ (e.g. adding `zipkin-server` dependency to a Spring-boot application) instead of the packaged application we release.

For proper usage, see the guides below.

## Quick-start

The quickest way to get started is to fetch the [latest released server](https://search.maven.org/remote_content?g=io.zipkin&a=zipkin-server&v=LATEST&c=exec) as a self-contained executable jar. Note that the Zipkin server requires minimum JRE 8. For example:

```bash
$ curl -sSL https://zipkin.io/quickstart.sh | bash -s
$ java -jar zipkin.jar
```

Once you've started, browse to http://your_host:9411 to find traces!

## Endpoints

The following endpoints are defined under the base url http://your_host:9411
* / - [UI](../zipkin-ui)
* /config.json - [Configuration for the UI](#configuration-for-the-ui)
* /api/v2 - [API](https://zipkin.io/zipkin-api/#/)
* /health - Returns 200 status if OK
* /info - Provides the version of the running instance
* /metrics - Includes collector metrics broken down by transport type
* /prometheus - Prometheus scrape endpoint

The [legacy /api/v1 API](https://zipkin.io/zipkin-api/#/) is still supported. Backends are decoupled from the
HTTP API via data conversion. This means you can still accept legacy data on new backends and visa versa. Enter
`https://zipkin.io/zipkin-api/zipkin-api.yaml` into the explore box of the Swagger UI to view the old definition

### CORS (Cross-origin Resource Sharing)

By default, all endpoints under `/api/v2` are configured to **allow** cross-origin requests.

This can be changed by modifying the property `zipkin.query.allowed-origins`.

For example, to allow CORS requests from `http://foo.bar.com`:

```
ZIPKIN_QUERY_ALLOWED_ORIGINS=http://foo.bar.com
```

See [Configuration](#configuration) for more about how Zipkin is configured.

### Service and Span names query
The [Zipkin API](https://zipkin.io/zipkin-api/#/default/get_services) does not include
a parameter for how far back to look for service or span names. In order
to prevent excessive load, service and span name queries are limited by
`QUERY_LOOKBACK`, which defaults to 24hrs (two daily buckets: one for
today and one for yesterday)

## Logging

By default, zipkin writes log messages to the console at INFO level and above. You can adjust
categories using the `logging.level.XXX` property.

For example, if you want to enable debug logging for all zipkin categories, you can start the server like so:

```bash
$ java -jar zipkin.jar --logging.level.zipkin2=DEBUG
```

See [Configuration](#configuration) for more about how Zipkin is configured.

### Advanced Logging Configuration
Under the covers, the server uses [Spring Boot - Logback integration](http://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html#howto-configure-logback-for-logging).
For example, you can add `--logging.exception-conversion-word=%wEx{full}` to dump full stack traces
instead of truncated ones.

## Metrics

Collector Metrics are exported to the path `/metrics`. These and additional metrics are exported
to the path `/prometheus`.

### Example Prometheus configuration
Here's an example `/prometheus` configuration, using the Prometheus
exposition [text format version 0.0.4](https://prometheus.io/docs/instrumenting/exposition_formats/)

```yaml
  - job_name: 'zipkin'
    scrape_interval: 5s
    metrics_path: '/prometheus'
    static_configs:
      - targets: ['localhost:9411']
    metric_relabel_configs:
      # Response code count
      - source_labels: [__name__]
        regex: '^status_(\d+)_(.*)$'
        replacement: '${1}'
        target_label: status
      - source_labels: [__name__]
        regex: '^status_(\d+)_(.*)$'
        replacement: '${2}'
        target_label: path
      - source_labels: [__name__]
        regex: '^status_(\d+)_(.*)$'
        replacement: 'http_requests_total'
        target_label: __name__
```

### Collector

Collector metrics are broken down by transport. The following are exported to the "/metrics" endpoint:

Metric | Description
--- | ---
counter.zipkin_collector.messages.$transport | cumulative messages received; should relate to messages reported by instrumented apps
counter.zipkin_collector.messages_dropped.$transport | cumulative messages dropped; reasons include client disconnects or malformed content
counter.zipkin_collector.bytes.$transport | cumulative message bytes
counter.zipkin_collector.spans.$transport | cumulative spans read; should relate to messages reported by instrumented apps
counter.zipkin_collector.spans_dropped.$transport | cumulative spans dropped; reasons include sampling or storage failures
gauge.zipkin_collector.message_spans.$transport | last count of spans in a message
gauge.zipkin_collector.message_bytes.$transport | last count of bytes in a message

## Configuration
We support ENV variable configuration, such as `STORAGE_TYPE=cassandra3`, as they are familiar to
administrators and easy to use in runtime environments such as Docker.

Here are the top-level configuration of Zipkin:
* `QUERY_PORT`: Listen port for the HTTP API and web UI; Defaults to 9411
* `QUERY_ENABLED`: `false` disables the HTTP read endpoints under '/api/v2'. This also disables the
UI, as it relies on the API. If your only goal is to restrict search, use `SEARCH_ENABLED` instead.
Defaults to true
* `SEARCH_ENABLED`: `false` disables searching in the query API and any indexing or post-processing
in the collector to support search. This does not disable the entire UI, as trace by ID and
dependency queries still operate. Disable this when you use another service (such as logs) to find
trace IDs. Defaults to true
* `QUERY_TIMEOUT`: Sets the hard timeout for query requests. Accepts any duration string (e.g., 100ms).
A value of 0 will disable the timeout completely. Defaults to 11s.
* `QUERY_LOG_LEVEL`: Log level written to the console; Defaults to INFO
* `QUERY_NAMES_MAX_AGE`: Controls the value of the `max-age` header zipkin-server responds with on
 http requests for autocompleted values in the UI (service names for example). Defaults to 300 seconds.
* `QUERY_LOOKBACK`: How many milliseconds queries can look back from endTs; Defaults to 24 hours (two daily buckets: one for today and one for yesterday)
* `STORAGE_TYPE`: SpanStore implementation: one of `mem`, `mysql`, `cassandra`, `elasticsearch`
* `COLLECTOR_SAMPLE_RATE`: Percentage of traces to retain, defaults to always sample (1.0).
* `AUTOCOMPLETE_KEYS`: list of span tag keys which will be returned by the `/api/v2/autocompleteTags` endpoint; Tag keys should be comma separated e.g. "instance_id,user_id,env"
* `AUTOCOMPLETE_TTL`: How long in milliseconds to suppress calls to write the same autocomplete key/value pair. Default 3600000 (1 hr)

### Configuration file overrides
Under the scenes, all configuration are managed by Spring Boot. This means that properties may also
be overridden by system properties or any other alternative [supported by Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html).

We use [yaml configuration](src/main/resources/zipkin-server-shared.yml) to bind shorter or more
idiomatic ENV variables to the Spring properties ultimately in use. While most users should only use
environment variables, some may desire a properties file approach to override settings. For example,
knowing we set `spring.config.name=zipkin-server`, Spring Boot will automatically look for a file
named `zipkin-server.properties` in the current directory, and the same properties we set in yaml
can be overridden that way.

If you choose to use property-based configuration instead of ENV variables, you are choosing to
self-support your configuration. This means you'll use [Spring Boot documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html)
or [StackOverflow](https://stackoverflow.com/questions/tagged/spring-boot) to resolve concerns
related to property resolution as opposed to raising issues or using our chat support. We have to
mention this because configuration of Spring implies vast responsibility and our resources must be
conserved for Zipkin related tasks.

## UI
Zipkin has a web UI, automatically included in the exec jar, and is hosted by default on port 9411.

When the UI loads, it reads default configuration from the `/config.json` endpoint.

{'fraction_non_alphanumeric': 0.08586055311334928, 'fraction_numerical': 0.00767903845083746, 'mean_word_length': 4.6373902132998746, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '887319', 'n_tokens_mistral': 5105, 'n_tokens_neox': 4835, 'n_words': 2105}