# Observability > Grafana

# Grafana

Artillery integrates with Grafana Cloud using OpenTelemetry protocol to send both metrics and traces.

## Quick Start

```yaml
plugins:
  publish-metrics:
    - type: 'open-telemetry'
      serviceName: my-service
      metrics:
        exporter: otlp-proto
        endpoint: '{{ $env.GRAFANA_OTLP_ENDPOINT }}'
        headers:
          Authorization: 'Basic {{ $env.GRAFANA_AUTH_CODE }}'
```

## Requirements

* Access Policy Token with correct scopes
* Account Information obtained in [`Cloud Portal`](https://grafana.com/docs/grafana-cloud/account-management/cloud-portal/) -> `OpenTelemetry` card -> `Configure`:
  * `Instance ID` (e.g. `130834`)
  * `OTLP Endpoint` (e.g. `https://otlp-gateway-prod-us-central-0.grafana.net/otlp`)

## Configuration

### Full Configuration Example

```yaml
plugins:
  publish-metrics:
    - type: 'open-telemetry'
      serviceName: <your-service-name>
      metrics:
        exporter: otlp-proto
        endpoint: '{{ $env.GRAFANA_OTLP_ENDPOINT }}'
        headers:
          Authorization: 'Basic {{ $env.GRAFANA_AUTH_CODE }}'
      traces:
        exporter: otlp-proto
        endpoint: '{{ $env.GRAFANA_OTLP_ENDPOINT }}'
        headers:
          Authorization: 'Basic {{ $env.GRAFANA_AUTH_CODE }}'
```

> **Info:** Note: Grafana requires `otlp-proto` exporter (HTTP/protobuf) rather than the default `otlp-http` (HTTP/JSON).

### Generating Auth Code

1. [Create an Access Policy Token](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/create-api-key/#create-a-grafana-cloud-access-policy) with the `metrics:write` and/or `traces:write` scopes depending on the data you will be sending.
2. Make a base64 encoding of the `<your-instance-id>:<your-token>` string and store it as an environment variable (e.g. `GRAFANA_AUTH_CODE`).

Example using command line:

```bash
echo -n "130834:your-access-token-here" | base64
```

## Supported Features

### Metrics

* All Artillery metrics are sent to Grafana Cloud
* Custom attributes can be added via the `attributes` configuration
* Metrics can be filtered using `includeOnly` or `excluded` options

### Traces

* Distributed tracing for HTTP and Playwright engines
* Sampling rate configuration
* Custom attributes for all spans
* Request name mapping

### Example with All Features

```yaml
plugins:
  publish-metrics:
    - type: 'open-telemetry'
      serviceName: load-test-service
      resourceAttributes:
        environment: production
        team: platform
      metrics:
        exporter: otlp-proto
        endpoint: '{{ $env.GRAFANA_OTLP_ENDPOINT }}'
        headers:
          Authorization: 'Basic {{ $env.GRAFANA_AUTH_CODE }}'
        attributes:
          test.type: load
          test.scenario: checkout-flow
      traces:
        exporter: otlp-proto
        endpoint: '{{ $env.GRAFANA_OTLP_ENDPOINT }}'
        headers:
          Authorization: 'Basic {{ $env.GRAFANA_AUTH_CODE }}'
        sampleRate: 0.1
        useRequestNames: true
        attributes:
          test.id: '{{ $testId }}'
```

## Debugging

Set `DEBUG=plugin:publish-metrics:open-telemetry` when running your tests to print out helpful debugging messages:

```sh
DEBUG=plugin:publish-metrics:open-telemetry artillery run my-script.yaml
```

## Reference

For additional information about sending OpenTelemetry data to Grafana, check their [documentation](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/).