Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Agent documentation to use doc/reference instead of relrefs #5555

Merged
merged 22 commits into from
Oct 24, 2023
Merged
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
2c9d731
Update migrate from static to use doc reference
clayton-cornell Oct 19, 2023
8022d68
Update links in opentelemetry topic
clayton-cornell Oct 20, 2023
f30307b
Update refernces in Promtail topic
clayton-cornell Oct 20, 2023
5e88c99
Add full URL to link
clayton-cornell Oct 20, 2023
465150f
Update Prometheus scrape relrefs
clayton-cornell Oct 20, 2023
e5f7080
Update clustering topic references
clayton-cornell Oct 20, 2023
d2555a2
More reference updates
clayton-cornell Oct 20, 2023
62c8bfd
Fix a build error
clayton-cornell Oct 20, 2023
ebe630f
Small correction update
clayton-cornell Oct 20, 2023
1d1dd8c
Small text update
clayton-cornell Oct 20, 2023
bd34f76
Merge branch 'main' into docs/replace-relrefs-with-docreferences
clayton-cornell Oct 20, 2023
eb2fd67
Merge branch 'main' into docs/replace-relrefs-with-docreferences
clayton-cornell Oct 21, 2023
7010ee5
Fix syntax for links in blockquotes
clayton-cornell Oct 23, 2023
fa99a24
Merge branch 'main' into docs/replace-relrefs-with-docreferences
clayton-cornell Oct 23, 2023
1c48bbb
Remove redundant relref definition
clayton-cornell Oct 23, 2023
b185864
Merge branch 'main' into docs/replace-relrefs-with-docreferences
clayton-cornell Oct 23, 2023
d9d0a8f
Merge branch 'main' into docs/replace-relrefs-with-docreferences
clayton-cornell Oct 24, 2023
2bff61a
Fix typos and links in notes
clayton-cornell Oct 24, 2023
b93b750
Correct GrafanaCloud to Grafana Cloud
clayton-cornell Oct 24, 2023
6b417c8
Fix link syntax
clayton-cornell Oct 24, 2023
463aae7
Merge branch 'main' into docs/replace-relrefs-with-docreferences
clayton-cornell Oct 24, 2023
0772f71
Fix some bad link text
clayton-cornell Oct 24, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 17 additions & 16 deletions docs/sources/flow/getting-started/collect-opentelemetry-data.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,6 @@ This topic describes how to:
* Configure batching
* Receive OpenTelemetry data over OTLP

[OpenTelemetry]: https://opentelemetry.io

## Components used in this topic

* [otelcol.auth.basic][]
Expand All @@ -30,12 +28,6 @@ This topic describes how to:
* [otelcol.processor.batch][]
* [otelcol.receiver.otlp][]

[otelcol.auth.basic]: {{< relref "../reference/components/otelcol.auth.basic.md" >}}
[otelcol.exporter.otlp]: {{< relref "../reference/components/otelcol.exporter.otlp.md" >}}
[otelcol.exporter.otlphttp]: {{< relref "../reference/components/otelcol.exporter.otlphttp.md" >}}
[otelcol.processor.batch]: {{< relref "../reference/components/otelcol.processor.batch.md" >}}
[otelcol.receiver.otlp]: {{< relref "../reference/components/otelcol.receiver.otlp.md" >}}

## Before you begin

* Ensure that you have basic familiarity with instrumenting applications with
Expand All @@ -45,8 +37,6 @@ This topic describes how to:
* Identify where Grafana Agent Flow will write received telemetry data.
* Be familiar with the concept of [Components][] in Grafana Agent Flow.

[Components]: {{< relref "../concepts/components.md" >}}

## Configure an OpenTelemetry Protocol exporter

Before components can receive OpenTelemetry data, you must have a component
Expand All @@ -61,8 +51,6 @@ to forward data to it.

> Refer to the list of available [Components][] for the full list of
> `otelcol.exporter` components that can be used to export OpenTelemetry data.
>
> [Components]: {{< relref "../reference/components/" >}}

To configure an `otelcol.exporter.otlp` component for exporting OpenTelemetry
data using OTLP, complete the following steps:
Expand Down Expand Up @@ -180,8 +168,6 @@ batch data before sending it to our exporter.
> `otelcol.processor` components that can be used to process OpenTelemetry
> data. You can chain processors by having one processor send data to another
> processor.
>
> [Components]: {{< relref "../reference/components/" >}}

To configure an `otelcol.processor.batch` component, complete the following
steps:
Expand Down Expand Up @@ -263,8 +249,6 @@ Agent Flow components.
> Refer to the list of available [Components][] for the full list of
> `otelcol.receiver` components that can be used to receive
> OpenTelemetry-compatible data.
>
> [Components]: {{< relref "../reference/components/" >}}

To configure an `otelcol.receiver.otlp` component for receiving OTLP data,
complete the following steps:
Expand Down Expand Up @@ -368,3 +352,20 @@ otelcol.exporter.otlp "default" {

For more information on receiving OpenTelemetry data using the OpenTelemetry
Protocol, refer to [otelcol.receiver.otlp][].

[OpenTelemetry]: https://opentelemetry.io

{{% docs/reference %}}
[otelcol.auth.basic]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.auth.basic.md"
[otelcol.auth.basic]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.auth.basic.md"
[otelcol.exporter.otlp]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.exporter.otlp.md"
[otelcol.exporter.otlp]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.exporter.otlp.md"
[otelcol.exporter.otlphttp]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.exporter.otlphttp.md"
[otelcol.exporter.otlphttp]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.exporter.otlphttp.md"
[otelcol.processor.batch]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.processor.batch.md"
[otelcol.processor.batch]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.processor.batch.md"
[otelcol.receiver.otlp]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/otelcol.receiver.otlp.md"
[otelcol.receiver.otlp]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/otelcol.receiver.otlp.md"
[Components]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md"
[Components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components.md"
{{% /docs/reference %}}
37 changes: 19 additions & 18 deletions docs/sources/flow/getting-started/collect-prometheus-metrics.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,12 @@ This topic describes how to:
* Configure metrics delivery
* Collect metrics from Kubernetes Pods

[Prometheus]: https://prometheus.io

## Components used in this topic

* [discovery.kubernetes][]
* [prometheus.remote_write][]
* [prometheus.scrape][]

[discovery.kubernetes]: {{< relref "../reference/components/discovery.kubernetes.md" >}}
[prometheus.remote_write]: {{< relref "../reference/components/prometheus.remote_write.md" >}}
[prometheus.scrape]: {{< relref "../reference/components/prometheus.scrape.md" >}}

## Before you begin

* Ensure that you have basic familiarity with instrumenting applications with
Expand All @@ -42,8 +36,6 @@ This topic describes how to:
Cloud, or Grafana Enterprise Metrics.
* Be familiar with the concept of [Components][] in Grafana Agent Flow.

[Components]: {{< relref "../concepts/components.md" >}}

## Configure metrics delivery

Before components can collect Prometheus metrics, you must have a component
Expand Down Expand Up @@ -168,7 +160,7 @@ To collect metrics from Kubernetes Pods, complete the following steps:
}
```

1. If you do not want to search for Pods in the Namespace Grafana
1. If you don't want to search for Pods in the Namespace Grafana
Agent is running in, set `own_namespace` to `false`.

2. Replace `NAMESPACE_NAMES` with a comma-delimited list of strings
Expand Down Expand Up @@ -233,10 +225,6 @@ To collect metrics from Kubernetes Pods, complete the following steps:
3. Replace `REMOTE_WRITE_LABEL` with the label chosen for your existing
`prometheus.remote_write` component.


[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement

The following example demonstrates configuring Grafana Agent to collect metrics
from running production Kubernetes Pods in the `default` Namespace:

Expand Down Expand Up @@ -377,10 +365,6 @@ To collect metrics from Kubernetes Services, complete the following steps:
3. Replace `REMOTE_WRITE_LABEL` with the label chosen for your existing
`prometheus.remote_write` component.


[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement

The following example demonstrates configuring Grafana Agent to collect metrics
from running production Kubernetes Services in the `default` Namespace:

Expand Down Expand Up @@ -497,4 +481,21 @@ prometheus.remote_write "default" {
}
```

[Objects]: {{< relref "../config-language/expressions/types_and_values.md#objects" >}}
[Prometheus]: https://prometheus.io
[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement
[Field Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
[Labels and Selectors]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement

{{% docs/reference %}}
[discovery.kubernetes]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/discovery.kubernetes.md"
[discovery.kubernetes]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/discovery.kubernetes.md"
[prometheus.remote_write]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.remote_write.md"
[prometheus.remote_write]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.remote_write.md"
[prometheus.scrape]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.scrape.md"
[prometheus.scrape]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.scrape.md"
[Components]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md"
[Components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components.md"
[Objects]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/config-language/expressions/types_and_values.md#objects"
[Objects]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/config-language/expressions/types_and_values.md#objects"
{{% /docs/reference %}}
23 changes: 15 additions & 8 deletions docs/sources/flow/getting-started/configure-agent-clustering.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,21 @@ individual agents can work together for workload distribution and high
availability.

{{% admonition type="note" %}}
Clustering is a [beta]({{< relref "../../stability.md#beta" >}}) feature. Beta features are subject to breaking
changes and may be replaced with equivalent functionality that covers the same
use case.
Clustering is a [beta](http://www.grafana.com/docs/agent/flow/stability.md#beta) feature.
clayton-cornell marked this conversation as resolved.
Show resolved Hide resolved
Beta features are subject to breaking changes and may be replaced with equivalent functionality that covers the same use case.
{{%/admonition %}}

This topic describes how to add clustering to an existing installation.

[clustering]: {{< relref "../concepts/clustering.md" >}}

## Configure Grafana Agent clustering with Helm Chart

This section will guide you through enabling clustering when Grafana Agent is
This section guides you through enabling clustering when Grafana Agent is
installed on Kubernetes using the [Grafana Agent Helm chart][install-helm].

[install-helm]: {{< relref "../setup/install/kubernetes.md" >}}
### Before you begin

- Ensure that your `values.yaml` file has `controller.type` set to
`statefulset`.

### Steps

Expand Down Expand Up @@ -61,4 +61,11 @@ To configure clustering:

2. Ensure that all expected nodes appear in the resulting table.

[UI]: {{< relref "../monitoring/debugging.md#clustering-page" >}}
{{% docs/reference %}}
[clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/clustering.md"
[clustering]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/clustering.md"
[install-helm]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/setup/install/kubernetes.md"
[install-helm]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/setup/install/kubernetes.md"
[UI]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging.md#component-detail-page"
[UI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/monitoring/debugging.md#component-detail-page"
{{% /docs/reference %}}
Original file line number Diff line number Diff line change
Expand Up @@ -18,23 +18,17 @@ auto-distribution allows a fleet of agents to work together to dynamically
distribute their scrape load, providing high-availability.

{{% admonition type="note" %}}
Clustering is a [beta]({{< relref "../../stability.md#beta" >}}) feature. Beta features are subject to breaking
Clustering is a [beta](https://www.grafana.com/docs/agent/<AGENT_VERSION>/stability#beta) feature. Beta features are subject to breaking
clayton-cornell marked this conversation as resolved.
Show resolved Hide resolved
changes and may be replaced with equivalent functionality that covers the same
use case.
{{%/admonition %}}

[Clustering]: {{< relref "../concepts/clustering.md" >}}

## Before you begin

- Familiarize yourself with how to [configure existing Grafana Agent installations][configure-grafana-agent].
- [Configure Prometheus metrics collection][].
- [Configure clustering][] of agents.
- Ensure that all of your clustered agents have the same config file.

[configure-grafana-agent]: {{< relref "../setup/configure" >}}
[Configure Prometheus metrics collection]: {{< relref "collect-prometheus-metrics.md" >}}
[Configure clustering]: {{< relref "./configure-agent-clustering.md" >}}
- Ensure that all of your clustered agents have the same configuration file.

## Steps

Expand All @@ -57,6 +51,17 @@ To distribute Prometheus metrics scrape load with clustering:
the `prometheus.scrape` components you modified.

2. Compare the Debug Info sections between two different agents to ensure
that they are not scraping the same sets of targets.

[UI]: {{< relref "../monitoring/debugging.md#component-detail-page" >}}
that they're not scraping the same sets of targets.

{{% docs/reference %}}
[Clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/clustering.md"
[Clustering]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/clustering.md"
[configure-grafana-agent]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/setup/configure"
[configure-grafana-agent]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/setup/configure"
[Configure Prometheus metrics collection]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/getting-started/collect-prometheus-metrics.md"
[Configure Prometheus metrics collection]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/getting-started/collect-prometheus-metrics.md"
[Configure clustering]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/getting-started/configure-agent-clustering.md"
[Configure clustering]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/getting-started/configure-agent-clustering.md"
[UI]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging.md#component-detail-page"
[UI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/monitoring/debugging.md#component-detail-page"
{{% /docs/reference %}}
54 changes: 34 additions & 20 deletions docs/sources/flow/getting-started/migrating-from-prometheus.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,29 +19,17 @@ This topic describes how to:
* Convert a Prometheus configuration to a flow configuration.
* Run a Prometheus configuration natively using Grafana Agent flow mode.

[Prometheus]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/

## Components used in this topic

* [prometheus.scrape][]
* [prometheus.remote_write][]

[prometheus.scrape]: {{< relref "../reference/components/prometheus.scrape.md" >}}
[prometheus.remote_write]: {{< relref "../reference/components/prometheus.remote_write.md" >}}

## Before you begin

* You must have an existing Prometheus configuration.
* You must have a set of Prometheus applications ready to push telemetry data to Grafana Agent.
* You must be familiar with the concept of [Components][] in Grafana Agent flow mode.

[Components]: {{< relref "../concepts/components.md" >}}
[convert]: {{< relref "../reference/cli/convert.md" >}}
[run]: {{< relref "../reference/cli/run.md" >}}
[Start the agent]: {{< relref "../setup/start-agent.md" >}}
[Flow Debugging]: {{< relref "../monitoring/debugging.md" >}}
[debugging]: #debugging

## Convert a Prometheus configuration

To fully migrate your configuration from [Prometheus] to Grafana Agent
Expand Down Expand Up @@ -79,7 +67,10 @@ additional features available in Grafana Agent flow mode.
any non-critical issues and output the flow configuration using a
best-effort conversion by including the `--bypass-errors` flag.

{{% admonition type="caution" %}}If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration. Make sure you fully test the converted configuration before using it in a production environment.{{% /admonition %}}
{{% admonition type="caution" %}}
If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration.
Make sure you fully test the converted configuration before using it in a production environment.
{{% /admonition %}}

{{< code >}}

Expand Down Expand Up @@ -139,14 +130,17 @@ This allows you to try flow mode without modifying your existing Prometheus conf
1. Refer to the Grafana Agent [Flow Debugging][] for more information about a running Grafana
Agent in flow mode.

1. If your Prometheus configuration cannot be converted and
loaded directly into Grafana Agent, diagnostic information
is sent to `stderr`. You can bypass any non-critical issues
1. If your Prometheus configuration cannot be converted and
loaded directly into Grafana Agent, diagnostic information
is sent to `stderr`. You can bypass any non-critical issues
and start the Agent by including the
`--config.bypass-conversion-errors` flag in addition to
`--config.format=prometheus`.

{{% admonition type="caution" %}}If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration. Do not use this flag in a production environment.{{% /admonition %}}
{{% admonition type="caution" %}}
If you bypass the errors, the behavior of the converted configuration may not match the original Prometheus configuration.
Do not use this flag in a production environment.
{{% /admonition %}}

## Example

Expand All @@ -173,8 +167,6 @@ remote_write:

The convert command takes the YAML file as input and outputs a [River][] file.

[River]: {{< relref "../config-language/_index.md" >}}

{{< code >}}

```static-binary
Expand Down Expand Up @@ -245,4 +237,26 @@ Furthermore, we recommend that you review the following checklist:
produced by Prometheus.
* Grafana Agent exposes the [Grafana Agent Flow UI][].

[Grafana Agent Flow UI]: {{< relref "../monitoring/debugging/#grafana-agent-flow-ui" >}}
[Prometheus]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/
[debugging]: #debugging

{{% docs/reference %}}
[prometheus.scrape]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.scrape.md"
[prometheus.scrape]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.scrape.md"
[prometheus.remote_write]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/components/prometheus.remote_write.md"
[prometheus.remote_write]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/components/prometheus.remote_write.md"
[Components]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/concepts/components.md"
[Components]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/concepts/components.md"
[convert]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/convert.md"
[convert]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/cli/convert.md"
[run]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/reference/cli/run.md"
[run]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/reference/cli/run.md"
[Start the agent]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/setup/start-agent.md"
[Start the agent]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/setup/start-agent.md"
[Flow Debugging]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging.md"
[Flow Debugging]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/monitoring/debugging.md"
[River]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/config-language/_index.md"
[River]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/config-language/_index.md"
[Grafana Agent Flow UI]: "/docs/agent/ -> /docs/agent/<AGENT_VERSION>/flow/monitoring/debugging#grafana-agent-flow-ui"
[Grafana Agent Flow UI]: "/docs/grafana-cloud/ -> /docs/grafana-cloud/monitor-infrastructure/agent/flow/monitoring/debugging#grafana-agent-flow-ui"
{{% /docs/reference %}}
Loading