# Observability > Newrelic

# New Relic

Artillery provides comprehensive integration with New Relic, supporting metrics, traces, and events through both native integration ([New Relic API](https://docs.newrelic.com/docs/apis/)) and OpenTelemetry.

## Quick Start

#### Tab

\`plugins:
  publish-metrics:
    \- type: newrelic
      licenseKey: "\{\{ $env.NR\_LICENSE\_KEY }}"\`

#### Tab

\`plugins:
  publish-metrics:
    \- type: open-telemetry
      serviceName: my-service
      metrics:
        endpoint: 'https://otlp.nr-data.net/v1/metrics'
        headers:
          api-key: '\{\{ $env.NR\_LICENSE\_KEY }}'\`

## Configuration Methods

### Native Integration

The native New Relic reporter supports sending [metrics](#metrics), [events](#events) and [traces](#traces-native) to New Relic.

#### Metrics

By default, all Artillery metrics will be sent to New Relic. Each Artillery metric will create a [custom New Relic metric](https://docs.newrelic.com/docs/apm/agents/nodejs-agent/extend-your-instrumentation/nodejs-custom-metrics/), which may have an associated cost.

#### Configuration Options

```yaml
config:
  plugins:
    publish-metrics:
      - type: newrelic
        # NR_LICENSE_KEY is an environment variable containing the New Relic license key
        licenseKey: "{{ $env.NR_LICENSE_KEY }}"
        region: eu
        prefix: "artillery.publish_metrics_plugin."
        attributes:
          - "testType:LoadTest"
          - "tool:Artillery"
```

| Name                    | Description                                                                                                                                        |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `licenseKey` (required) | The license key for the account you want to send the metrics to                                                                                    |
| `region`                | `us` (default) or `eu`. If your account hosts data in the EU data center set the region to `eu`.                                                   |
| `prefix`                | Set a prefix for metric names created by Artillery; defaults to `artillery.`                                                                       |
| `attributes`            | A list of `name:value` strings to use as tags for all metrics sent during a test                                                                   |
| `excluded`              | A list of metric names which should not be sent to New Relic. Defaults to an empty list, i.e. all metrics are sent to New Relic.                   |
| `includeOnly`           | A list of specific metrics to send to New Relic. No other metrics will be sent. Defaults to an empty list, i.e. all metrics are sent to New Relic. |
| `event`                 | Set to send a New Relic event when test starts/finishes. See [event specific configuration](#events)                                               |
| `traces`                | Set to send traces to New Relic. See [traces specific configuration](#traces-native)                                                                      |

#### Events

The reporter supports sending a New Relic event on test start and test finish. To enable set the `event` option and configure it with the `accountId`.

#### Event Configuration

```yaml
config:
  plugins:
    publish-metrics:
      - type: newrelic
        licenseKey:  "{{ $env.NR_LICENSE_KEY }}"
        event:
          accountId: "{{ $env.NR_ACCOUNT_ID }}"
          eventType: "Artillery_load_test"
          attributes:
            - "alertType:info"
            - "priority:low"
            - "testId:{{ $testId }}"
```

| Name                   | Description                                                                                                                                                                                                            |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId` (required) | Your New Relic [account ID](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/account-id/).                                                                                                   |
| `eventType`            | Set to customize the event's name, defaults to `Artillery_io_Test`. Must be a string that is a combination of alphanumeric characters, underscores, and colons.                                                        |
| `send`                 | Set to `false` to turn off the event. By default, if `event` is configured, it will be sent. This option makes it possible to turn event creation on/off on the fly (e.g. via an environment variable)                 |
| `attributes`           | Optional list of `name:value` strings to use as attributes/tags for events sent during a test. By default Artillery sends the `target: `, `timestamp: ` and `phase: 'Test Started' / 'Test Finished'` attributes. |

> **Info:** *Note: Check [character restrictions for
> attributes](https://docs.newrelic.com/docs/data-apis/ingest-apis/event-api/introduction-event-api/#instrument)*

#### Traces (Native)

New Relic `tracing` feature is available for both [HTTP](../../engines/http) and [Playwright](../../engines/playwright) engines, and the [tracing data available](/docs/observability/opentelemetry#artillery-engines) is different depending on the engine used.

An additional `plugins.publish-metrics.spans.exported` metric will be recorded and will appear in your reports when `tracing` is enabled. It represents the number of spans exported to New Relic.

#### Trace Configuration Options

```yaml
config:
  plugins:
    publish-metrics:
      - type: newrelic
        licenseKey:  "{{ $env.NR_LICENSE_KEY }}"
        traces:
          serviceName: service_name
          sampleRate: 0.5
          replaceSpanNameRegex:
            - pattern: get_user_[a-zA-Z0-9]+
              as: get_user_id
          attributes:
            - testType:LoadTest
            - tool:Artillery
```

| Name                                                         | Description                                                                                                                                                                             |
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `serviceName`                                                | Name of your service. Defaults to `Artillery-test`                                                                                                                                      |
| `sampleRate`                                                 | Sample rate. Percentage of traces to send represented by a value between 0 and 1. (defaults to 1 - all traces are sent)                                                                 |
| `useRequestNames`                                            | If set to `true` the request `name`s provided in test script will be used as span names                                                                                                 |
| `attributes`                                                 | Custom attributes to be added to each span in `key: value` pair format.                                                                                                                 |
| `replaceSpanNameRegex`  | A list of replacement maps that consist of: `pattern` - regex pattern to match against the span names  `as` - string to replace the matched pattern in the span names |

### OpenTelemetry Integration

You can also send data to New Relic using OpenTelemetry protocol. This is useful when you want standardized telemetry or are already using OpenTelemetry in your infrastructure.

#### Requirements

* [License Key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#overview-keys)
* Region (EU or US)

#### Configuration

```yaml
plugins:
  publish-metrics:
    - type: 'open-telemetry'
      serviceName: <your-service-name>
      metrics:
        endpoint: 'https://{{ $env.NEW_RELIC_OTLP_ENDPOINT }}/v1/metrics'
        headers:
          api-key: '{{ $env.NR_LICENSE_KEY }}'
      traces:
        endpoint: 'https://{{ $env.NEW_RELIC_OTLP_ENDPOINT }}/v1/traces'
        headers:
          api-key: '{{ $env.NEW_RELIC_LICENSE_KEY }}'
```

#### Endpoints

| Organisation    | Base URL                        |
| --------------- | ------------------------------- |
| US OTLP         | `https://otlp.nr-data.net`      |
| EU OTLP         | `https://otlp.eu01.nr-data.net` |
| US FedRAMP OTLP | `https://gov-otlp.nr-data.net`  |

## Examples

### Complete Native Integration

```yaml
config:
  plugins:
    publish-metrics:
      - type: newrelic
        licenseKey: "{{ $env.NR_LICENSE_KEY }}"
        region: us
        prefix: "artillery.publish_metrics_plugin."
        attributes:
          - "testType:LoadTest"
          - "tool:Artillery"
        event:
          accountId: "{{ $env.NR_ACCOUNT_ID }}"
          eventType: "Artillery_load_test"
          attributes:
            - "alertType:info"
            - "priority:low"
            - "testId:{{ $testId }}"
        traces:
          serviceName: service_name
          sampleRate: 0.5
          useRequestNames: true
          attributes:
            - testType:LoadTest
            - tool:Artillery
```

## Debugging

Set `DEBUG=plugin:publish-metrics:newrelic` when running your tests to print out helpful debugging messages when sending metrics to New Relic.

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

## Reference

For more information, consult the [New Relic documentation](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app/#review-settings).