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.

Sign up for GitHub

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

Cleanup more alloy docs #134

Merged
merged 4 commits into from
Apr 5, 2024
Merged

Cleanup more alloy docs #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d428aa5
Clean up beyla topic
clayton-cornell Apr 5, 2024
89a22f0
General syntax cleanup
clayton-cornell Apr 5, 2024
3590447
Update pyroscope sytnax and style
clayton-cornell Apr 5, 2024
2838e99
Fix and clarify main page
clayton-cornell Apr 5, 2024
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
4 changes: 2 additions & 2 deletions docs/sources/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ Some of these features include:
* **Clustering support:** {{< param "PRODUCT_NAME" >}} has native clustering support.
Clustering helps distribute the workload and ensures you have high availability.
You can quickly create horizontally scalable deployments with minimal resource and operational overhead.
* **Security:** {{< param "PRODUCT_NAME" >}} helps you manage authentication credentials and connect to HashiCorp Vaults or Kubernetes clusters to retrieve secrets.
* **Debugging utilities:** {{< param "PRODUCT_NAME" >}} provides troubleshooting support and an embedded [user interface][UI] to help you identify and resolve configuration problems.
* **Security:** {{< param "PRODUCT_NAME" >}} helps you manage authentication credentials and connect to HashiCorp Vault servers or Kubernetes clusters to retrieve Kubernetes secrets.
* **Debugging utilities:** {{< param "PRODUCT_NAME" >}} provides debugging tools such as an embedded [user interface][UI] to help you identify and resolve configuration problems.

## Explore

Expand Down
4 changes: 2 additions & 2 deletions docs/sources/_index.md.t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ Some of these features include:
* **Clustering support:** {{< param "PRODUCT_NAME" >}} has native clustering support.
Clustering helps distribute the workload and ensures you have high availability.
You can quickly create horizontally scalable deployments with minimal resource and operational overhead.
* **Security:** {{< param "PRODUCT_NAME" >}} helps you manage authentication credentials and connect to HashiCorp Vaults or Kubernetes clusters to retrieve secrets.
* **Debugging utilities:** {{< param "PRODUCT_NAME" >}} provides troubleshooting support and an embedded [user interface][UI] to help you identify and resolve configuration problems.
* **Security:** {{< param "PRODUCT_NAME" >}} helps you manage authentication credentials and connect to HashiCorp Vault servers or Kubernetes clusters to retrieve Kubernetes secrets.
* **Debugging utilities:** {{< param "PRODUCT_NAME" >}} provides debugging tools such as an embedded [user interface][UI] to help you identify and resolve configuration problems.

## Explore

Expand Down
110 changes: 50 additions & 60 deletions docs/sources/reference/components/beyla.ebpf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,10 @@ You can configure the component to collect telemetry data from a specific port o
The component exposes metrics that can be collected by a Prometheus scrape component, and traces that can be forwarded to an OTEL exporter component.

{{< admonition type="note" >}}
To run this component, {{< param "PRODUCT_NAME" >}} requires administrative (`sudo`) privileges, or at least it needs to be granted the `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` capability. In Kubernetes environments, app armour must be disabled for the Deployment or DaemonSet running {{< param "PRODUCT_NAME" >}}.
To run this component, {{< param "PRODUCT_NAME" >}} requires administrative (`sudo`) privileges, or at least it needs to be granted the `CAP_SYS_ADMIN` and `CAP_SYS_PTRACE` capability.
In Kubernetes environments, app armour must be disabled for the Deployment or DaemonSet running {{< param "PRODUCT_NAME" >}}.
{{< /admonition >}}

[Grafana Beyla]: https://github.com/grafana/beyla
[eBPF]: https://ebpf.io/

## Usage

```alloy
Expand All @@ -33,11 +31,10 @@ beyla.ebpf "<LABEL>" {

`beyla.ebpf` supports the following arguments:

Name | Type | Description | Default | Required
---- | ---- |-----------------------------------------------------------| ------- | --------
`open_port` | `string` | The port of the running service for Beyla automatically instrumented with eBPF. | | no
`excutable_name` | `string` | The name of the executable to match for Beyla automatically instrumented with eBPF. | | no

Name | Type | Description | Default | Required
-----------------|----------|-------------------------------------------------------------------------------------|---------|---------
`open_port` | `string` | The port of the running service for Beyla automatically instrumented with eBPF. | | no
`excutable_name` | `string` | The name of the executable to match for Beyla automatically instrumented with eBPF. | | no

`open_port` accepts a comma-separated list of ports (for example, `80,443`), and port ranges (for example, `8000-8999`).
If the executable matches only one of the ports in the list, it is considered to match the selection criteria.
Expand All @@ -48,37 +45,28 @@ If the executable matches only one of the ports in the list, it is considered to

The following blocks are supported inside the definition of `beyla.ebpf`:

Hierarchy | Block | Description | Required
--------- | ----- | ----------- | --------
routes | [routes][] | Configures the routes to match HTTP paths into user-provided HTTP routes. | no
attributes | [attributes][] | Configures the Beyla attributes for the component. | no
Hierarchy | Block | Description | Required
------------------------|----------------|----------------------------------------------------------------------------------------------------|---------
routes | [routes][] | Configures the routes to match HTTP paths into user-provided HTTP routes. | no
attributes | [attributes][] | Configures the Beyla attributes for the component. | no
attributes > kubernetes | [kubernetes][] | Configures decorating of the metrics and traces with Kubernetes metadata of the instrumented Pods. | no
discovery | [discovery][] | Configures the discovery for instrumentable processes matching a given criteria. | no
discovery > services | [services][] | Configures the discovery for the component. | no
output | [output][] | Configures where to send received telemetry data. | yes

The `>` symbol indicates deeper levels of nesting. For example,
`attributes > kubernetes` refers to a `kubernetes` block defined inside an
`attributes` block.
discovery | [discovery][] | Configures the discovery for instrumentable processes matching a given criteria. | no
discovery > services | [services][] | Configures the discovery for the component. | no
output | [output][] | Configures where to send received telemetry data. | yes

[routes]: #routes-block
[attributes]: #attributes-block
[kubernetes]: #kubernetes-block
[discovery]: #discovery-block
[services]: #services-block
[output]: #output-block
The `>` symbol indicates deeper levels of nesting.
For example,`attributes > kubernetes` refers to a `kubernetes` block defined inside an `attributes` block.

### attributes block

This block allows you to configure how some attributes for metrics and traces are decorated.

It contains the following blocks:
[kubernetes]: #kubernetes-block

#### kubernetes block

Name | Type | Description | Default | Required
---- | ---- |-----------------------------------------------------------| ------- | --------
Name | Type | Description | Default | Required
---------|----------|--------------------------------------------|---------|---------
`enable` | `string` | Enable the Kubernetes metadata decoration. | `false` | no

If set to `true`, Beyla will decorate the metrics and traces with Kubernetes metadata. The following labels will be added:
Expand All @@ -95,19 +83,18 @@ If set to `true`, Beyla will decorate the metrics and traces with Kubernetes met

If set to `false`, the Kubernetes metadata decorator will be disabled.

If set to `autodetect`, Beyla will try to automatically detect if it is running inside Kubernetes, and enable the metadata decoration if that is the case.

If set to `autodetect`, Beyla will try to automatically detect if it is running inside Kubernetes, and enable the metadata decoration if that's the case.

### routes block

This block is used to configure the routes to match HTTP paths into user-provided HTTP routes.

Name | Type | Description | Default | Required
---- | ---- |-----------------------------------------------------------| ------- | --------
`patterns` | `list(string)` | List of provided URL path patterns to set the `http.route` trace/metric property | | no
`ignore_patterns` | `list(string)` | List of provided URL path patterns to ignore from `http.route` trace/metric property. | | no
`ignore_mode` | `string` | The mode to use when ignoring patterns. | | no
`unmatched` | `string` | Specifies what to do when a trace HTTP path does not match any of the `patterns` entries | | no
Name | Type | Description | Default | Required
------------------|----------------|-------------------------------------------------------------------------------------------|---------|---------
`patterns` | `list(string)` | List of provided URL path patterns to set the `http.route` trace/metric property | | no
`ignore_patterns` | `list(string)` | List of provided URL path patterns to ignore from `http.route` trace/metric property. | | no
`ignore_mode` | `string` | The mode to use when ignoring patterns. | | no
`unmatched` | `string` | Specifies what to do when a trace HTTP path does not match any of the `patterns` entries. | | no

`patterns` and `ignored_patterns` are a list of patterns which a URL path with specific tags which allow for grouping path segments (or ignored them).
The matcher tags can be in the `:name` or `{name}` format.
Expand All @@ -124,31 +111,30 @@ The matcher tags can be in the `:name` or `{name}` format.
- Any path components that have numbers or characters outside of the ASCII alphabet (or `-` and _), are replaced by an asterisk `*`.
- Any alphabetical components that don’t look like words are replaced by an asterisk `*`.


### discovery block

This block is used to configure the discovery for instrumentable processes matching a given criteria.

It contains the following blocks:
[services]: #services-block

### services block

In some scenarios, Beyla will instrument a wide variety of services, such as a Kubernetes DaemonSet that instruments all the services in a node.
This block allows you to filter the services to instrument based on their metadata.

Name | Type | Description | Default | Required
---- | ---- |-----------------------------------------------------------| ------- | --------
`name ` | `string` | The name of the service to match. | | no
`namespace` | `string` | The namespace of the service to match. | | no
`open_ports` | `string` | The port of the running service for Beyla automatically instrumented with eBPF. | | no
`path` | `string` | The path of the running service for Beyla automatically instrumented with eBPF. | | no
Name | Type | Description | Default | Required
-------------|----------|---------------------------------------------------------------------------------|---------|---------
`name ` | `string` | The name of the service to match. | | no
`namespace` | `string` | The namespace of the service to match. | | no
`open_ports` | `string` | The port of the running service for Beyla automatically instrumented with eBPF. | | no
`path` | `string` | The path of the running service for Beyla automatically instrumented with eBPF. | | no

`name` defines a name for the matching instrumented service. It is used to populate the `service.name` OTEL property and/or the `service_name` Prometheus property in the exported metrics/traces.
`open_port` accepts a comma-separated list of ports (for example, `80,443`), and port ranges (for example, `8000-8999`). If the executable matches only one of the ports in the list, it is considered to match the selection criteria.
`name` defines a name for the matching instrumented service.
It is used to populate the `service.name` OTEL property and/or the `service_name` Prometheus property in the exported metrics/traces.
`open_port` accepts a comma-separated list of ports (for example, `80,443`), and port ranges (for example, `8000-8999`).
If the executable matches only one of the ports in the list, it is considered to match the selection criteria.
`path` accepts a regular expression to be matched against the full executable command line, including the directory where the executable resides on the file system.


### output block

The `output` block configures a set of components to forward the resulting telemetry data to.
Expand All @@ -168,32 +154,26 @@ Configure the `traces` argument to send traces data to other components.
The following fields are exported and can be referenced by other components.

Name | Type | Description
----------|---------------------|----------------------------------------------------------
----------|---------------------|------------------------------------------------------------------------------------
`targets` | `list(map(string))` | The targets that can be used to collect metrics of instrumented services with eBPF.

For example, the `targets` can either be passed to a `discovery.relabel` component to rewrite the targets' label sets or to a `prometheus.scrape` component that collects the exposed metrics.

The exported targets use the configured [in-memory traffic][] address specified by the [run command][].

[in-memory traffic]: ../../../concepts/component_controller#in-memory-traffic
[run command]: ../../cli/run/

## Component health

`beyla.ebpf` is only reported as unhealthy if given an invalid
configuration.
`beyla.ebpf` is only reported as unhealthy if given an invalid configuration.

## Debug information

`beyla.ebpf` does not expose any component-specific debug
information.
`beyla.ebpf` does not expose any component-specific debug information.

## Example

### Metrics

This example uses a [`prometheus.scrape` component][scrape] to collect metrics from `beyla.ebpf` of
the specified port:
This example uses a [`prometheus.scrape` component][scrape] to collect metrics from `beyla.ebpf` of the specified port:

```alloy
beyla.ebpf "default" {
Expand Down Expand Up @@ -224,8 +204,6 @@ Replace the following:
- _`<USERNAME>`_: The username to use for authentication to the remote_write API.
- _`<PASSWORD>`_: The password to use for authentication to the remote_write API.

[scrape]: ../prometheus.scrape/

### Traces

This example gets traces from `beyla.ebpf` and forwards them to `otlp`:
Expand Down Expand Up @@ -256,6 +234,18 @@ Replace the following:
- _`<OPEN_PORT>`_: The port of the running service for Beyla automatically instrumented with eBPF.
- _`<OTLP_ENDPOINT>`_: The endpoint of the OpenTelemetry Collector to send traces to.

[Grafana Beyla]: https://github.com/grafana/beyla
[eBPF]: https://ebpf.io/
[routes]: #routes-block
[attributes]: #attributes-block
[kubernetes]: #kubernetes-block
[discovery]: #discovery-block
[services]: #services-block
[output]: #output-block
[in-memory traffic]: ../../../concepts/component_controller#in-memory-traffic
[run command]: ../../cli/run/
[scrape]: ../prometheus.scrape/

<!-- START GENERATED COMPATIBLE COMPONENTS -->

## Compatible components
Expand Down
Loading
Loading