Add initial Hugo docs to be published on Github pages

Signed-off-by: Fabian Stäber <[email protected]>

Author: fstab

docs/.gitignore

@@ -0,0 +1 @@
+.hugo_build.lock

docs/README.md

@@ -0,0 +1,37 @@
+Docs
+----
+
+This directory contains [hugo](https://gohugo.io) documentation to be published in Github pages.
+
+Run Locally
+-----------
+
+```
+hugo server -D
+```
+
+This will serve the docs on [http://localhost:1313](http://localhost:1313).
+
+Deploy to Github Pages
+----------------------
+
+Changes to the `main` branch will be deployed automatically with Github actions.
+
+Set-up Notes
+------------
+
+Here's how the initial `docs/` folder was set up:
+
+```
+hugo new site docs
+cd docs/
+mkdir -p themes/hugo-geekdoc/
+curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/download/v0.41.1/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1
+```
+
+Create the initial `hugo.toml` file as described in [https://geekdocs.de/usage/getting-started/](https://geekdocs.de/usage/getting-started/).
+
+Update Geekdocs
+---------------
+
+The docs use the [Geekdocs](https://geekdocs.de/) theme. The theme is checked in to Github in the `./docs/themes/hugo-geekdoc/` folder. To update [Geekdocs](https://geekdocs.de/), remove the current folder and create a new one with the latest [release](https://github.com/thegeeklab/hugo-geekdoc/releases). There are no local modifications in `./docs/themes/hugo-geekdoc/`.

docs/archetypes/default.md

@@ -0,0 +1,5 @@
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++

docs/content/_index.md

@@ -0,0 +1,34 @@
+---
+title: "client_java"
+---
+
+Brainstorming of potential topics:
+
+* Getting started
+  * Quickstart
+  * Metrics Types
+  * Callbacks
+  * Native Histograms
+  * Naming conventions (unit, total, dots)
+  * Exposition Formats
+  * How to use the API for high performance applications
+* Exporters
+  * HTTPServer
+  * Servlet
+  * Pushgateway
+  * OpenTelemetry
+* Instrumentations
+  * JVM metrics
+  * Servlet filter
+* OpenTelemetry
+  * OpenTelemetry exporter
+  * Combining Prometheus `client_java` with the OpenTelemetry instrumentation agent.
+  * Trace sampling and Exemplars
+  * API comparision: OpenTelemetry vs Prometheus
+  * Performance comparison: OpenTelemetry vs Prometheus
+* Examples
+  * todo: examples directory
+* Spring Boot Actuator / Micrometer
+* Runtime Configuration
+* Backwards Compatibility with Simpleclient
+* Requirements (Java 8)

docs/content/getting-started/_index.md

@@ -0,0 +1,4 @@
+---
+title: Getting Started
+weight: 1
+---

docs/content/getting-started/callbacks.md

@@ -0,0 +1,57 @@
+---
+title: Callbacks
+weight: 5
+---
+
+The section on [metric types](../metric-types) showed how to use metrics that actively maintain their state.
+
+This section shows how to create callback-based metrics, i.e. metrics that invoke a callback at scrape time to get the current values.
+
+For example, let's assume we have two instances of a `Cache`, a `coldCache` and a `hotCache`. The following implements a callback-based `cache_size_bytes` metric:
+
+```java
+Cache coldCache = new Cache();
+Cache hotCache = new Cache();
+
+GaugeWithCallback.builder()
+    .name("cache_size_bytes")
+    .help("Size of the cache in Bytes.")
+    .unit(Unit.BYTES)
+    .labelNames("state")
+    .callback(callback -> {
+        callback.call(coldCache.sizeInBytes(), "cold");
+        callback.call(hotCache.sizeInBytes(), "hot");
+    })
+    .register();
+```
+
+The resulting text format looks like this:
+
+```
+# TYPE cache_size_bytes gauge
+# UNIT cache_size_bytes bytes
+# HELP cache_size_bytes Size of the cache in Bytes.
+cache_size_bytes{state="cold"} 78.0
+cache_size_bytes{state="hot"} 83.0
+```
+
+Better examples of callback metrics can be found in the `prometheus-metrics-instrumentation-jvm` module.
+
+The available callback metric types are:
+
+* `GaugeWithCallback` for gauges.
+* `CounterWithCallback` for counters.
+* `SummaryWithCallback` for summaries.
+
+The API for gauges and counters is very similar. For summaries the callback has a few more parameters, because it accepts a count, a sum, and quantiles:
+
+```java
+SummaryWithCallback.builder()
+    .name("example_callback_summary")
+    .help("help message.")
+    .labelNames("status")
+    .callback(callback -> {
+        callback.call(cache.getCount(), cache.getSum(), Quantiles.EMPTY, "ok");
+    })
+    .register();
+```

docs/content/getting-started/labels.md

@@ -0,0 +1,149 @@
+---
+title: Labels
+weight: 3
+---
+
+The following shows an example of a Prometheus metric in text format:
+
+```
+# HELP payments_total total number of payments
+# TYPE payments_total counter
+payments_total{status="error",type="paypal"} 1.0
+payments_total{status="success",type="credit card"} 3.0
+payments_total{status="success",type="paypal"} 2.0
+```
+
+The example shows a counter metric named `payments_total` with two labels: `status` and `type`. Each individual data point (each line in text format) is identified by the unique combination of its metric name and its label name/value pairs.
+
+Creating a Metric with Labels
+-----------------------------
+
+Labels are supported for all metric types. We are using counters in this example, however the `labelNames()` and `labelValues()` methods are the same for other metric types.
+
+The following code creates the counter above.
+
+```java
+Counter counter = Counter.builder()
+    .name("payments_total")
+    .help("total number of payments")
+    .labelNames("type", "status")
+    .register();
+
+counter.labelValues("credit card", "success").inc(3.0);
+counter.labelValues("paypal", "success").inc(2.0);
+counter.labelValues("paypal", "error").inc(1.0);
+```
+
+The label names have to be specified when the metric is created and cannot change. The label values are created on demand when values are observed.
+
+Creating a Metric without Labels
+--------------------------------
+
+Labels are optional. The following example shows a metric without labels:
+
+```java
+Counter counter = Counter.builder()
+    .name("payments_total")
+    .help("total number of payments")
+    .register();
+
+counter.inc(3.0);
+```
+
+Cardinality Explosion
+---------------------
+
+Each combination of label names and values will result in a new data point, i.e. a new line in text format.
+Therefore, a good label should have only a small number of possible values.
+If you select labels with many possible values, like unique IDs or timestamps, you may end up with an enormous number of data points.
+This is called cardinality explosion.
+
+Here's a bad example, don't do this:
+
+```java
+Counter loginCount = Counter.builder()
+    .name("logins_total")
+    .help("total number of logins")
+    .labelNames("user_id", "timestamp") // not a good idea, this will result in too many data points
+    .register();
+
+String userId = UUID.randomUUID().toString();
+String timestamp = Long.toString(System.currentTimeMillis());
+
+loginCount.labelValues(userId, timestamp).inc();
+```
+
+Initializing Label Values
+-------------------------
+
+If you register a metric without labels, it will show up immediately with initial value of zero.
+
+However, metrics with labels only show up after the label values are first used. In the example above
+
+```java
+counter.labelValues("paypal", "error").inc();
+```
+
+The data point
+
+```
+payments_total{status="error",type="paypal"} 1.0
+```
+
+will jump from non-existent to value 1.0. You will never see it with value 0.0.
+
+This is usually not an issue. However, if you find this annoying and want to see all possible label values from the start, you can initialize label values with `initLabelValues()` like this:
+
+```java
+Counter counter = Counter.builder()
+    .name("payments_total")
+    .help("total number of payments")
+    .labelNames("type", "status")
+    .register();
+
+counter.initLabelValues("credit card", "success");
+counter.initLabelValues("credit card", "error");
+counter.initLabelValues("paypal", "success");
+counter.initLabelValues("paypal", "error");
+```
+
+Now the four combinations will be visible from the start with initial value zero.
+
+```
+# HELP payments_total total number of payments
+# TYPE payments_total counter
+payments_total{status="error",type="credit card"} 0.0
+payments_total{status="error",type="paypal"} 0.0
+payments_total{status="success",type="credit card"} 0.0
+payments_total{status="success",type="paypal"} 0.0
+```
+
+Expiring Unused Label Values
+----------------------------
+
+There is no automatic expiry of unused label values (yet). Once a set of label values is used, it will remain there forever.
+
+However, you can programmatically remove label values like this:
+
+```java
+counter.remove("paypal", "error");
+counter.remove("paypal", "success");
+```
+
+Const Labels
+------------
+
+If you have labels values that never change, you can specify them in the builder as `constLabels()`:
+
+```java
+Counter counter = Counter.builder()
+    .name("payments_total")
+    .help("total number of payments")
+    .constLabels(Labels.of("env", "dev"))
+    .labelNames("type", "status")
+    .register();
+```
+
+However, most use cases for `constLabels()` are better covered by target labels set by the scraping Prometheus server,
+or by one specific metric (e.g. a `build_info` or a `machine_role` metric). See also
+[target labels, not static scraped labels](https://prometheus.io/docs/instrumenting/writing_exporters/#target-labels-not-static-scraped-labels).