Adds loki destination skeleton (#23)

* Adds loki destination skeleton * Remove theme elements that are now available in the theme * Get rid of version numbers in the navbar * Review corrections, part 1 * Review corrections, part 2 * Generalize gRPC authentication chunk So it can be used both for opentelemetry and loki drivers * Delete unneeded comments
axoflow · Sep 29, 2023 · 6dd2121 · 6dd2121
1 parent d26b89a
commit 6dd2121
Show file tree

Hide file tree

Showing 8 changed files with 179 additions and 46 deletions.
diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss
@@ -5,27 +5,4 @@ Nothing defined here. The Hugo project that uses this theme can override Bootstr
 assets/scss/_styles_project.scss
 
 */
-@import "tocbot";
-
-.warning-block {
-    border-left: 6px solid red;
-    background: #FFFFFF;
-    padding: 16px;
-  }
-.property-optional::after {
-  content: "optional";
-  background-color: $secondary;
-  font-size: 14px;
-  line-height: 22px;
-  padding: 3px 6px;
-  text-transform: uppercase;
-}
-.property-required::after {
-  content: "required";
-  background-color: $primary;
-  color: white;
-  font-size: 14px;
-  line-height: 22px;
-  padding: 3px 6px;
-  text-transform: uppercase;
-}
+@import "../../themes/docsy-axoflow/assets/scss/_styles_project.scss";
diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss
@@ -1,8 +1,2 @@
-$navbar-dark-color: white; // Set navbar text to white to increase contrast
-$blue: #496bb8 !default; // Override breadcrumb and sidebar text color to increase contrast
-$primary: #313671 !default;
-
-$dark: black;
-
-$google_font_name: "Montserrat";
-$google_font_family: "Montserrat:300,300i,400,400i,700,700i";
+// Placeholder file for project-specific customizations
+@import "../../themes/docsy-axoflow/assets/scss/_variables_project.scss";
diff --git a/assets/scss/tocbot.css b/assets/scss/tocbot.css
diff --git a/config/_default/config.toml b/config/_default/config.toml
@@ -1,5 +1,5 @@
 
-title = "AxoSyslog 4"
+title = "AxoSyslog"
 
 theme = ["docsy-axoflow", "docsy"]
 
@@ -18,8 +18,8 @@ enableGitInfo = true
 
 [languages]
 [languages.en]
-title = "AxoSyslog - a syslog-ng distribution 4.0-4.x"
-description = "Documentation for AxoSyslog version 4, a syslog-ng distribution"
+title = "AxoSyslog - a syslog-ng distribution"
+description = "Documentation for AxoSyslog, a syslog-ng distribution"
 languageName ="English"
 # Weight used for sorting.
 weight = 1

diff --git a/content/chapter-destinations/destination-loki/_index.md b/content/chapter-destinations/destination-loki/_index.md
@@ -0,0 +1,125 @@
+---
+title: "loki: Grafana Loki"
+weight:  3050
+---
+<!-- This file is under the copyright of Axoflow, and licensed under Apache License 2.0, except for using the Axoflow and AxoSyslog trademarks. -->
+
+Available in {{% param "product.abbrev" %}} version 4.4 and later.
+
+The `loki()` destination sends your log data to [Grafana Loki](https://grafana.com/docs/loki/) via gRPC, using the same message format documented for the [Grafana Loki HTTP endpoint](https://grafana.com/docs/loki/latest/reference/api/#push-log-entries-to-loki).
+
+Sample configuration:
+
+```shell
+loki(
+    url("localhost:9096")
+    labels(
+        "app" => "$PROGRAM",
+        "host" => "$HOST",
+    )
+
+    workers(16)
+    batch-timeout(10000)
+    batch-lines(1000)
+);
+```
+
+## Options
+
+The `loki()` destination has the following options.
+
+## batch-lines()
+
+|          |        |
+| -------- | ------ |
+| Type:    | number |
+| Default: | 0      |
+
+{{% include-headless "chunk/option-description-destination-batch-lines.md" %}}
+
+{{% include-headless "chunk/option-destination-batch-timeout.md" %}}
+
+{{< include-headless "chunk/grpc-authentication.md" >}}
+
+## keep-alive()
+
+Configures how {{% param "product.abbrev" %}} sends [gRPC keepalive pings](https://grpc.io/docs/guides/keepalive/).
+
+### max-pings-without-data()
+
+|          |                    |
+| -------- | ------------------ |
+| Type:    | integer |
+| Default: |                 |
+
+*Description:* The maximum number of gRPC pings that can be sent when there is no data/header frame to be sent. {{% param "product.abbrev" %}} won't send any pings after this limit. Set it to 0 disable this restriction and keep sending pings.
+
+### time()
+
+|          |                    |
+| -------- | ------------------ |
+| Type:    | number [milliseconds] |
+| Default: |                 |
+
+*Description:* The period (in milliseconds) after which {{% param "product.abbrev" %}} sends a gRPC keepalive ping.
+
+### timeout()
+
+|          |                    |
+| -------- | ------------------ |
+| Type:    | number [milliseconds] |
+| Default: | 10                 |
+
+*Description:* The time (in milliseconds) {{% param "product.abbrev" %}} waits for an acknowledgement.
+
+## labels()
+
+|          |         |
+| -------- | ------- |
+| Type:    |  |
+| Default: | See the description |
+
+The labels applied to the message as they are sent to the destination. Use the following format:
+
+```shell
+labels(
+    "name-of-the-label-in-the-output" => "field-of-the-message"
+)
+```
+
+Default value:
+
+<!-- FIXME -->
+
+## template()
+
+|          |                                                    |
+| -------- | -------------------------------------------------- |
+| Type:    | template or template-function             |
+| Default: | `$ISODATE $HOST $MSGHDR$MSG` |
+
+*Description:* Specifies a template defining the logformat to be used in the destination. Macros are described in {{% xref "/chapter-manipulating-messages/customizing-message-format/reference-macros/_index.md" %}}. For details on template functions, see {{% xref "/chapter-manipulating-messages/customizing-message-format/reference-template-functions/_index.md" %}}.
+
+## timestamp()
+
+|          |                            |
+| -------- | -------------------------- |
+| Type:    | `current`, `received`, or `msg` |
+| Default: | `current` |
+
+*Description:* Sets the timestamp to use for the messages sent to Loki. This is important because Loki accepts data only if their timestamp is monotonously increasing, out of order messages are rejected. The possible values for this option are:
+
+- `current`: Use the timestamp when {{% param "product.abbrev" %}} processes the message in the output. This guarantees that the timestamp is monotonously increasing, but in some cases can significantly differ from the time when the message was generated.
+- `msg`: Use the original timestamp of the message.
+- `received`: Use the timestamp when {{% param "product.abbrev" %}} has received the message.
+
+## url()
+
+|          |                            |
+| -------- | -------------------------- |
+| Type:    | string |
+| Default: | `localhost:9095` |
+
+*Description:* The URL of the Loki endpoint.
+
+{{< include-headless "chunk/option-destination-threaded-workers.md" >}}
diff --git a/content/chapter-destinations/opentelemetry/_index.md b/content/chapter-destinations/opentelemetry/_index.md
@@ -56,7 +56,7 @@ log non_otel_to_otel_tls {
 };
 ```
 
-{{< include-headless "chunk/opentelemetry-authentication.md" >}}
+{{< include-headless "chunk/grpc-authentication.md" >}}
 
 {{< include-headless "chunk/option-destination-threaded-batching.md" >}}
 

diff --git a/content/chapter-sources/opentelemetry/_index.md b/content/chapter-sources/opentelemetry/_index.md
@@ -29,7 +29,7 @@ log otel_forward_mode_alts {
 };
 ```
 
-{{< include-headless "chunk/opentelemetry-authentication.md" >}}
+{{< include-headless "chunk/grpc-authentication.md" >}}
 
 ## `port()` {#port}
 

diff --git a/...ess/chunk/opentelemetry-authentication.md → ...ent/headless/chunk/grpc-authentication.md b/...ess/chunk/opentelemetry-authentication.md → ...ent/headless/chunk/grpc-authentication.md
@@ -1,20 +1,25 @@
 ---
 ---
 <!-- This file is under the copyright of Axoflow, and licensed under Apache License 2.0, except for using the Axoflow and AxoSyslog trademarks. -->
-## `auth()` {#auth}
 
-You can set authentication in the `auth()` option of the `opentelemetry()` driver. By default, authentication is disabled (`auth(insecure())`).
+<!-- Used in the opentelemetry() and loki() drivers -->
+## auth() {#auth}
+
+You can set authentication in the `auth()` option of the driver. By default, authentication is disabled (`auth(insecure())`).
 
 The following authentication methods are available in the `auth()` block:
 
-### `adc()` {#adc}
+### adc() {#adc}
 
 [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials). This authentication method is only available for destinations.
 
-### `alts()` {#alts}
+### alts() {#alts}
 
 [Application Layer Transport Security (ALTS)](https://grpc.io/docs/languages/cpp/alts/) is a simple to use authentication, only available within Google's infrastructure. It accepts the `target-service-account()` option, where you can list service accounts to match against when authenticating the server.
 
+{{< tabpane text=true right=true >}}
+{{% tab header="Driver:" disabled=true /%}}
+{{% tab header="`opentelemetry()`" lang="opentelemetry" %}}
 ```shell
 source {
     opentelemetry(
@@ -23,18 +28,33 @@ source {
     );
   };
 ```
+{{% /tab %}}
+{{% tab header="`loki()`" lang="loki" %}}
+```shell
+destination {
+    loki(
+      port(12345)
+      auth(alts())
+    );
+  };
+```
+{{% /tab %}}
+{{< /tabpane >}}
 
-### `insecure()` {#insecure}
+### insecure() {#insecure}
 
 This is the default method, authentication is disabled (`auth(insecure())`).
 
-### `tls()` {#tls}
+### tls() {#tls}
 
 <!-- FIXME xinclude these from the other tls blocks -->
 
 `tls()` accepts the `key-file()`, `cert-file()`, `ca-file()` and `peer-verify()` (possible values:
 `required-trusted`, `required-untrusted`, `optional-trusted` and `optional-untrusted`) options.
 
+{{< tabpane text=true right=true >}}
+{{% tab header="Driver:" disabled=true /%}}
+{{% tab header="`opentelemetry()`" lang="opentelemetry" %}}
 ```shell
 destination {
     opentelemetry(
@@ -49,8 +69,26 @@ destination {
     );
   };
 ```
+{{% /tab %}}
+{{% tab header="`loki()`" lang="loki" %}}
+```shell
+destination {
+    loki(
+      url("your-loki-server:12346")
+      auth(
+        tls(
+          ca-file("/path/to/ca.pem")
+          key-file("/path/to/key.pem")
+          cert-file("/path/to/cert.pem")
+        )
+      )
+    );
+  };
+```
+{{% /tab %}}
+{{< /tabpane >}}
 
 > Note:
 >
-> - `tls(peer-verify())` is not available for the `opentelemetry()` destination.
-> - The `opentelemetry()` drivers have a different `tls()` block implementation from the `network()` or `http()` drivers. Most features are the same.
+> - `tls(peer-verify())` is not available for the `opentelemetry()` and `loki()` destination.
+> - The gRPC-based drivers (`opentelemetry()` and `loki()`) have a different `tls()` block implementation from the `network()` or `http()` drivers. Most features are the same.
-Original file line number
+Diff line change
@@ Expand Up / @@ -56,7 +56,7 @@ log non_otel_to_otel_tls { @@
     };
     ```
-    {{< include-headless "chunk/opentelemetry-authentication.md" >}}
+    {{< include-headless "chunk/grpc-authentication.md" >}}
     {{< include-headless "chunk/option-destination-threaded-batching.md" >}}
@@ Expand Down @@