# Observability > Splunk

# Splunk

Artillery integrates with [Splunk Observability Cloud](https://www.splunk.com/en_us/download/o11y-cloud-free-trial.html) to send both metrics and events via the Ingest API.

## Quick Start

```yaml
config:
  plugins:
    publish-metrics:
      - type: splunk
        accessToken: '{{ $env.SP_ACCESS_TOKEN }}'
```

## Configuration

By default, all Artillery metrics will be sent to Splunk. Each Artillery metric will create a custom Splunk metric, which will have an associated charge.

### Configuration Options

| Name          | Description                                                                                                                                          |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accessToken` | Your organization's `INGEST` [access token](https://docs.splunk.com/Observability/admin/authentication/authentication-tokens/org-tokens.html#admin-org-tokens) (required) |
| `realm`       | Override the default Splunk endpoint (defaults to `us0`). A realm is a self-contained deployment that hosts organizations. You can find your realm name on your profile page |
| `prefix`      | Prefix for metric names created by Artillery (defaults to `artillery.`) |
| `dimensions`  | List of `name:value` strings to use as dimensions for all metrics. [Learn more about dimensions](https://docs.splunk.com/Observability/metrics-and-metadata/metrics-dimensions-mts.html#dimensions) |
| `excluded`    | List of metric names which should not be sent to Splunk |
| `includeOnly` | List of specific metrics to send to Splunk. No other metrics will be sent |
| `event`       | Configuration for sending events when test starts/finishes |

### Event Configuration

Events can be sent to Splunk when your test starts and finishes:

| Name         | Description                                                                                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventType`  | Event name. Cannot contain blank spaces. Defaults to `Artillery_io_Test` |
| `send`       | Set to `false` to disable events. Useful for toggling via environment variables |
| `dimensions` | List of `name:value` strings for event dimensions. Default dimensions include `target`, `timestamp`, and `phase` |
| `properties` | List of `name:value` strings for event properties. [Learn about dimensions vs properties](https://docs.splunk.com/Observability/metrics-and-metadata/metrics-dimensions-mts.html#metadata-dimensions-custom-properties-tags-and-attributes) |

## Examples

### Complete Configuration

```yaml
config:
  plugins:
    publish-metrics:
      - type: splunk
        realm: eu0
        # SP_ACCESS_TOKEN is an environment variable containing the API key
        accessToken: '{{ $env.SP_ACCESS_TOKEN }}'
        prefix: 'artillery.publish_metrics_plugin.'
        dimensions:
          - 'host:server_1'
          - 'host_id:1.2.3.4'
        event:
          eventType: 'Artillery_load_test'
          dimensions:
            - 'environment:production'
            - 'testId:{{ $testId }}'
          properties:
            - 'use:QA'
```

### Filtering Metrics

```yaml
config:
  plugins:
    publish-metrics:
      - type: splunk
        accessToken: '{{ $env.SP_ACCESS_TOKEN }}'
        realm: us1
        includeOnly:
          - http.response_time
          - http.requests
          - errors.count
        dimensions:
          - 'service:checkout'
          - 'team:platform'
```

## Managing Data in Splunk

For information on how to manage data ingested through the Splunk API, consult [Splunk docs](https://docs.splunk.com/Observability/metrics-and-metadata/metrics-finder-metadata-catalog.html#use-the-metric-finder-and-metadata-catalog).

## Debugging

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

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

## Best Practices

1. **Use meaningful dimensions**: Choose dimension names that follow Splunk's [naming requirements](https://docs.splunk.com/Observability/metrics-and-metadata/metric-names.html#dimension-name-requirements)
2. **Control costs**: Use `includeOnly` or `excluded` to limit the number of custom metrics sent
3. **Organize by service**: Use dimensions to group metrics by service, environment, and team