Skip to content

Commit

Permalink
Additional eding for syntax style
Browse files Browse the repository at this point in the history
  • Loading branch information
@clayton-cornell
clayton-cornell committed Nov 22, 2023
1 parent 6ca5c43 commit 2dea63d
Show file tree
Hide file tree
Showing 12 changed files with 378 additions and 485 deletions.
55 changes: 23 additions & 32 deletions docs/sources/flow/reference/components/loki.relabel.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,19 @@ title: loki.relabel

# loki.relabel

The `loki.relabel` component rewrites the label set of each log entry passed to
its receiver by applying one or more relabeling `rule`s and forwards the
results to the list of receivers in the component's arguments.
The `loki.relabel` component rewrites the label set of each log entry passed to its receiver by applying one or more relabeling `rule`s and forwards the results to the list of receivers in the component's arguments.

If no labels remain after the relabeling rules are applied, then the log
entries are dropped.
If no labels remain after the relabeling rules are applied, then the log entries are dropped.

The most common use of `loki.relabel` is to filter log entries or standardize
the label set that is passed to one or more downstream receivers. The `rule`
blocks are applied to the label set of each log entry in order of their
appearance in the configuration file. The configured rules can be retrieved by
calling the function in the `rules` export field.
The most common use of `loki.relabel` is to filter log entries or standardize the label set that is passed to one or more downstream receivers.
The `rule` blocks are applied to the label set of each log entry in order of their appearance in the configuration file.
The configured rules can be retrieved by calling the function in the `rules` export field.

If you're looking for a way to process the log entry contents, take a look at
[the `loki.process` component][loki.process] instead.
If you're looking for a way to process the log entry contents, take a look at [the `loki.process` component][loki.process] instead.

[loki.process]: {{< relref "./loki.process.md" >}}

Multiple `loki.relabel` components can be specified by giving them
different labels.
Multiple `loki.relabel` components can be specified by giving them different labels.

## Usage

Expand All @@ -50,32 +43,32 @@ loki.relabel "LABEL" {

The following arguments are supported:

Name | Type | Description | Default | Required
---- | ---- | ----------- | ------- | --------
`forward_to` | `list(receiver)` | Where to forward log entries after relabeling. | | yes
`max_cache_size` | `int` | The maximum number of elements to hold in the relabeling cache | 10,000 | no
Name | Type | Description | Default | Required
-----------------|------------------|----------------------------------------------------------------|---------|---------
`forward_to` | `list(receiver)` | Where to forward log entries after relabeling. | | yes
`max_cache_size` | `int` | The maximum number of elements to hold in the relabeling cache | 10,000 | no

## Blocks

The following blocks are supported inside the definition of `loki.relabel`:

Hierarchy | Name | Description | Required
--------- | ---- | ----------- | --------
rule | [rule][] | Relabeling rules to apply to received log entries. | no
Hierarchy | Name | Description | Required
----------|----------|----------------------------------------------------|---------
rule | [rule][] | Relabeling rules to apply to received log entries. | no

[rule]: #rule-block

### rule block
### rule

{{< docs/shared lookup="flow/reference/components/rule-block-logs.md" source="agent" version="<AGENT VERSION>" >}}
{{< docs/shared lookup="flow/reference/components/rule-block-logs.md" source="agent" version="<AGENT_VERSION>" >}}

## Exported fields

The following fields are exported and can be referenced by other components:

Name | Type | Description
---- | ---- | -----------
`receiver` | `receiver` | The input receiver where log lines are sent to be relabeled.
Name | Type | Description
-----------|----------------|-------------------------------------------------------------
`receiver` | `receiver` | The input receiver where log lines are sent to be relabeled.
`rules` | `RelabelRules` | The currently configured relabeling rules.

## Component health
Expand All @@ -89,16 +82,15 @@ In those cases, exported fields are kept at their last healthy values.

## Debug metrics

* `loki_relabel_entries_processed` (counter): Total number of log entries processed.
* `loki_relabel_entries_written` (counter): Total number of log entries forwarded.
* `loki_relabel_cache_misses` (counter): Total number of cache misses.
* `loki_relabel_cache_hits` (counter): Total number of cache hits.
* `loki_relabel_cache_misses` (counter): Total number of cache misses.
* `loki_relabel_cache_size` (gauge): Total size of relabel cache.
* `loki_relabel_entries_processed` (counter): Total number of log entries processed.
* `loki_relabel_entries_written` (counter): Total number of log entries forwarded.

## Example

The following example creates a `loki.relabel` component that only forwards
entries whose 'level' value is set to 'error'.
The following example creates a `loki.relabel` component that only forwards entries whose 'level' value is set to 'error'.

```river
loki.relabel "keep_error_only" {
Expand All @@ -111,4 +103,3 @@ loki.relabel "keep_error_only" {
}
}
```

42 changes: 22 additions & 20 deletions docs/sources/flow/reference/components/loki.source.api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ title: loki.source.api

`loki.source.api` receives log entries over HTTP and forwards them to other `loki.*` components.

The HTTP API exposed is compatible with [Loki push API][loki-push-api] and the `logproto` format. This means that other [`loki.write`][loki.write] components can be used as a client and send requests to `loki.source.api` which enables using the Agent as a proxy for logs.
The HTTP API exposed is compatible with [Loki push API][loki-push-api] and the `logproto` format.
This means that other [`loki.write`][loki.write] components can be used as a client and send requests to `loki.source.api` which enables using the Agent as a proxy for logs.

[loki.write]: {{< relref "./loki.write.md" >}}
[loki-push-api]: https://grafana.com/docs/loki/latest/api/#push-log-entries-to-loki
Expand All @@ -24,7 +25,7 @@ The HTTP API exposed is compatible with [Loki push API][loki-push-api] and the `
loki.source.api "LABEL" {
http {
listen_address = "LISTEN_ADDRESS"
listen_port = PORT
listen_port = PORT
}
forward_to = RECEIVER_LIST
}
Expand All @@ -33,9 +34,9 @@ loki.source.api "LABEL" {
The component will start HTTP server on the configured port and address with the following endpoints:

- `/loki/api/v1/push` - accepting `POST` requests compatible with [Loki push API][loki-push-api], for example, from another Grafana Agent's [`loki.write`][loki.write] component.
- `/loki/api/v1/raw` - accepting `POST` requests with newline-delimited log lines in body. This can be used to send NDJSON or plaintext logs. This is compatible with promtail's push API endpoint - see [promtail's documentation][promtail-push-api] for more information. NOTE: when this endpoint is used, the incoming timestamps cannot be used and the `use_incoming_timestamp = true` setting will be ignored.
- `/loki/api/v1/raw` - accepting `POST` requests with newline-delimited log lines in body. This can be used to send NDJSON or plaintext logs. This is compatible with Promtail's push API endpoint - see [promtail's documentation][promtail-push-api] for more information. NOTE: when this endpoint is used, the incoming timestamps cannot be used and the `use_incoming_timestamp = true` setting will be ignored.
- `/loki/ready` - accepting `GET` requests - can be used to confirm the server is reachable and healthy.
- `/api/v1/push` - internally reroutes to `/loki/api/v1/push`
- `/api/v1/push` - internally reroutes to `/loki/api/v1/push`
- `/api/v1/raw` - internally reroutes to `/loki/api/v1/raw`


Expand All @@ -45,43 +46,43 @@ The component will start HTTP server on the configured port and address with the

`loki.source.api` supports the following arguments:

Name | Type | Description | Default | Required
--------------------------|----------------------|------------------------------------------------------------|---------|----------
`forward_to` | `list(LogsReceiver)` | List of receivers to send log entries to. | | yes
`use_incoming_timestamp` | `bool` | Whether or not to use the timestamp received from request. | `false` | no
`labels` | `map(string)` | The labels to associate with each received logs record. | `{}` | no
`relabel_rules` | `RelabelRules` | Relabeling rules to apply on log entries. | `{}` | no
Name | Type | Description | Default | Required
-------------------------|----------------------|------------------------------------------------------------|---------|---------
`forward_to` | `list(LogsReceiver)` | List of receivers to send log entries to. | | yes
`labels` | `map(string)` | The labels to associate with each received logs record. | `{}` | no
`relabel_rules` | `RelabelRules` | Relabeling rules to apply on log entries. | `{}` | no
`use_incoming_timestamp` | `bool` | Whether or not to use the timestamp received from request. | `false` | no

The `relabel_rules` field can make use of the `rules` export value from a
[`loki.relabel`][loki.relabel] component to apply one or more relabeling rules to log entries before they're forwarded to the list of receivers in `forward_to`.
The `relabel_rules` field can make use of the `rules` export value from a [`loki.relabel`][loki.relabel] component to apply one or more relabeling rules to log entries before they're forwarded to the list of receivers in `forward_to`.

[loki.relabel]: {{< relref "./loki.relabel.md" >}}

## Blocks

The following blocks are supported inside the definition of `loki.source.api`:

Hierarchy | Name | Description | Required
-----------|----------|----------------------------------------------------|----------
`http` | [http][] | Configures the HTTP server that receives requests. | no
Hierarchy | Name | Description | Required
----------|----------|----------------------------------------------------|---------
`http` | [http][] | Configures the HTTP server that receives requests. | no

[http]: #http

### http

{{< docs/shared lookup="flow/reference/components/loki-server-http.md" source="agent" version="<AGENT VERSION>" >}}
{{< docs/shared lookup="flow/reference/components/loki-server-http.md" source="agent" version="<AGENT_VERSION>" >}}

## Exported fields

`loki.source.api` does not export any fields.
`loki.source.api` doesn't export any fields.

## Component health

`loki.source.api` is only reported as unhealthy if given an invalid configuration.

## Debug metrics

The following are some of the metrics that are exposed when this component is used. Note that the metrics include labels such as `status_code` where relevant, which can be used to measure request success rates.
The following are some of the metrics that are exposed when this component is used.
Note that the metrics include labels such as `status_code` where relevant, which can be used to measure request success rates.

* `loki_source_api_request_duration_seconds` (histogram): Time (in seconds) spent serving HTTP requests.
* `loki_source_api_request_message_bytes` (histogram): Size (in bytes) of messages received in the request.
Expand All @@ -90,7 +91,9 @@ The following are some of the metrics that are exposed when this component is us

## Example

This example starts an HTTP server on `0.0.0.0` address and port `9999`. The server receives log entries and forwards them to a `loki.write` component while adding a `forwarded="true"` label. The `loki.write` component will send the logs to the specified loki instance using basic auth credentials provided.
This example starts an HTTP server on `0.0.0.0` address and port `9999`.
The server receives log entries and forwards them to a `loki.write` component while adding a `forwarded="true"` label.
The `loki.write` component will send the logs to the specified loki instance using basic auth credentials provided.

```river
loki.write "local" {
Expand All @@ -116,4 +119,3 @@ loki.source.api "loki_push_api" {
}
}
```

Loading

0 comments on commit 2dea63d

Please sign in to comment.