diff --git a/docs/articles/log-plugin-new-relic.md b/docs/articles/log-plugin-new-relic.md new file mode 100644 index 000000000..d1036c27c --- /dev/null +++ b/docs/articles/log-plugin-new-relic.md @@ -0,0 +1,62 @@ +--- +title: New Relic Plugin +sidebar_label: New Relic Logging +--- + +The New Relic Log plugin enables pushing logs to New Relic. + + + +## Setup + +To add the New Relic logging plugin to your Zuplo project, add the following +code to your `zuplo.runtime.ts` file. Set the `url` parameter (optional) to the +value of your New Relic log API endpoint and the `NEW_RELIC_API_KEY` environment +variable to your New Relic API key. + +Any custom fields you want to include in the log entry can be added to the +`fields` property. These values will be appended to every log entry. + +```ts title="modules/zuplo.runtime.ts" +import { + RuntimeExtensions, + NewRelicLoggingPlugin, + environment, +} from "@zuplo/runtime"; + +export function runtimeInit(runtime: RuntimeExtensions) { + runtime.addPlugin( + new NewRelicLoggingPlugin({ + // Optional, defaults to "https://log-api.newrelic.com/log/v1" + url: "https://log-api.newrelic.com/log/v1", + apiKey: environment.NEW_RELIC_API_KEY, + service: "MyAPI", // Optional, defaults to "Zuplo" + fields: { + field1: "value1", + field2: "value2", + }, + }), + ); +} +``` + +## Standard Fields + +Every log entry will include the following fields: + +- `message` - The log message and data +- `level` - The level of the log, for example `error`, `info`, etc. +- `timestamp` - The time the log was created (in milliseconds since epoch) +- `service` - The name of the service (defaults to "Zuplo" or custom value + provided) +- `environment` - The deployment name of the Zuplo API +- `environment_type` - Where the Zuplo API is running. Values are `edge`, + `working-copy`, or `local` +- `environment_stage` - If the environment is `working-copy`, `preview`, or + `production` +- `request_id` - The UUID of the request (the value of the `zp-rid` header) +- `atomic_counter` - An atomic number that's used to order logs that have the + same timestamp +- `ray_id` - The network provider identifier (i.e. Cloudflare RayID) of the + request +- `log_source` - The source of the log entry diff --git a/docs/articles/logging.md b/docs/articles/logging.md index d5e3e407f..bbecf39e0 100644 --- a/docs/articles/logging.md +++ b/docs/articles/logging.md @@ -18,6 +18,7 @@ instructions on how to configure logging, see the documentation for each plugin: - [AWS CloudWatch](./log-plugin-aws-cloudwatch.md) - [DataDog](./log-plugin-datadog.md) - [Dynatrace](./log-plugin-dynatrace.md) +- [New Relic](./log-plugin-new-relic.md) - [Google Cloud Logging](./log-plugin-gcp.md) - [Loki](./log-plugin-loki.md) - [Sumo Logic](./log-plugin-sumo.md) diff --git a/docs/articles/metrics-plugins.md b/docs/articles/metrics-plugins.md index 3ae2ecfd7..99c4573da 100644 --- a/docs/articles/metrics-plugins.md +++ b/docs/articles/metrics-plugins.md @@ -10,6 +10,7 @@ Zuplo supports logging to the following sources: - DataDog (Beta) - Dynatrace (Beta) +- New Relic (Beta) If you would like to log to a different source, reach out to support@zuplo.com and we'd be happy to work with you to add a new logging plugin. @@ -201,3 +202,68 @@ export default async function (request: ZuploRequest, context: ZuploContext) { return "What zup?"; } ``` + +### New Relic (Beta) + +By default, we send all metrics to New Relic. However, you have the option below +to configure which metrics you want to send. + +New Relic's Metric API provides a powerful way to monitor your API's performance. The metrics are sent to New Relic's Metric API endpoint (https://metric-api.newrelic.com/metric/v1) by default, but you can customize this if needed. + +```ts +import { + RuntimeExtensions, + NewRelicMetricsPlugin, + environment, +} from "@zuplo/runtime"; + +export function runtimeInit(runtime: RuntimeExtensions) { + runtime.addPlugin( + new NewRelicMetricsPlugin({ + apiKey: environment.NEW_RELIC_API_KEY, + // Optional: customize the URL if needed + // url: "https://metric-api.newrelic.com/metric/v1", + // You can add custom attributes to all metrics + attributes: { + service: "my-service-name", + environment: environment.ENVIRONMENT ?? "DEVELOPMENT", + }, + metrics: { + latency: true, + requestContentLength: true, + responseContentLength: true, + }, + // You can also choose to add additional attributes to include in the metrics + include: { + country: false, + httpMethod: false, + statusCode: false, + path: false, + }, + }), + ); +} +``` + +The above configuration applies globally for all metrics sent to New Relic. If you +wish to dynamically configure information for a particular ZuploContext, you can +use the `NewRelicMetricsPlugin` in your code. Currently, the only configuration +you can set is the attributes. The values you set here will be appended to those set +globally in the `zuplo.runtime.ts` file. + +```ts +import { + ZuploContext, + ZuploRequest, + NewRelicMetricsPlugin, +} from "@zuplo/runtime"; + +export default async function (request: ZuploRequest, context: ZuploContext) { + const someValue = "hello"; + NewRelicMetricsPlugin.setContext(context, { + attributes: { "my-custom-attribute": someValue }, + }); + + return "What zup?"; +} +``` diff --git a/sidebar.ts b/sidebar.ts index a415de472..d2167cb1c 100644 --- a/sidebar.ts +++ b/sidebar.ts @@ -81,6 +81,7 @@ export const docs: SidebarEntry = [ "articles/log-plugin-aws-cloudwatch", "articles/log-plugin-datadog", "articles/log-plugin-dynatrace", + "articles/log-plugin-new-relic", "articles/log-plugin-sumo", "articles/custom-logging-example", "articles/log-export",