zuplo 6.67.32 → 6.68.0

package/docs/articles/log-plugin-datadog.mdx

@@ -0,0 +1,84 @@
+---
+title: Datadog Plugin
+sidebar_label: Datadog Logging
+---
+
+The Datadog Log plugin enables pushing logs to Datadog.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the Datadog logging plugin to your Zuplo project, add the following code
+to your `zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  DataDogLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new DataDogLoggingPlugin({
+      // Optional, defaults to the Datadog logs API endpoint
+      url: "https://http-intake.logs.datadoghq.com/api/v2/logs",
+      apiKey: environment.DATADOG_API_KEY,
+      source: "MyAPI", // Optional, defaults to "Zuplo"
+      tags: {
+        tag: "hello",
+      },
+      fields: {
+        field1: "value1",
+        field2: "value2",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `DataDogLoggingPlugin` constructor accepts an options object with the
+following properties:
+
+- `apiKey` - (required) Your Datadog API key for authentication
+- `url` - (optional) The Datadog logs intake URL. Defaults to the Datadog logs
+  API endpoint
+- `source` - (optional) The source of the logs, typically the name of the
+  application or service. Defaults to "Zuplo"
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+- `tags` - (optional) Custom
+  [tags](https://docs.datadoghq.com/getting_started/tagging/) to include in each
+  log entry as key-value pairs
+
+### Custom Fields
+
+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.
+
+### Tags
+
+Any custom tags you want to include in the log entry can be added to the `tags`
+property. These values will be appended to every log entry.
+
+## Default Fields
+
+Every log entry will include the following fields (in snake_case format for
+Datadog):
+
+- `timestamp` - The time the log was created (ISO 8601 format)
+- `severity` - The log level (for example, `ERROR`, `INFO`, `DEBUG`, `WARN`)
+- `message` - The complete log message and data
+- `msg` - The first string message extracted from the log entry
+- `environment_type` - Where the Zuplo API is running. Values are `edge`,
+  `working-copy`, or `local`
+- `environment_stage` - The deployment stage: `working-copy`, `preview`, or
+  `production`
+- `request_id` - The UUID of the request (the value of the `zp-rid` header)
+- `atomic_counter` - An atomic counter used to order logs with identical
+  timestamps
+- `ray_id` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request

package/docs/articles/log-plugin-dynatrace.mdx

@@ -0,0 +1,75 @@
+---
+title: Dynatrace Plugin
+sidebar_label: Dynatrace Logging
+---
+
+The Dynatrace Log plugin enables pushing logs to Dynatrace.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the Dynatrace logging plugin to your Zuplo project, add the following
+code to your `zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  DynaTraceLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new DynaTraceLoggingPlugin({
+      // This is the URL of your Dynatrace logs ingest API
+      url: "https://xxxxxxx.live.dynatrace.com/api/v2/logs/ingest",
+      apiToken: environment.DYNATRACE_API_TOKEN,
+      fields: {
+        field1: "value1",
+        field2: "value2",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `DynaTraceLoggingPlugin` constructor accepts an options object with the
+following properties:
+
+- `url` - (required) The Dynatrace logs ingest API URL (for example,
+  `https://xxxxxxx.live.dynatrace.com/api/v2/logs/ingest`)
+- `apiToken` - (required) Your Dynatrace API token. The API token requires the
+  `events.ingest` scope
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+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.
+
+## Default Fields
+
+Every log entry will include the following fields:
+
+- `timestamp` - The time the log was created (ISO 8601 format)
+- `severity` - The log level (for example, `ERROR`, `INFO`, `DEBUG`, `WARN`)
+- `content` - The log message and data
+- `custom.environmentType` - Where the Zuplo API is running. Values are `edge`,
+  `working-copy`, or `local`
+- `custom.environmentStage` - The deployment stage: `working-copy`, `preview`,
+  or `production`
+- `requestId` - The UUID of the request (the value of the `zp-rid` header)
+- `custom.atomicCounter` - An atomic counter used to order logs with identical
+  timestamps
+- `custom.rayId` - The network provider identifier (for example, Cloudflare Ray
+  ID) of the request
+
+:::note
+
+Dynatrace places custom fields under the `custom` namespace in the log entries.
+
+:::

package/docs/articles/log-plugin-gcp.mdx

@@ -0,0 +1,75 @@
+---
+title: Google Cloud Logging Plugin
+sidebar_label: Google Cloud Logging
+---
+
+The Google Cloud Log plugin enables pushing logs to your Google Cloud project.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+Before you can use this plugin, you will need to create a GCP Service account
+that grants your Zuplo API to write logs. Create a new GCP Service account and
+give it the **Logs Writer (roles/logging.logWriter)** permission. Create a key
+for the service account in JSON format.
+
+After you have downloaded the JSON formatted service account, save it as a
+secret environment variable in your Zuplo project.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  GoogleCloudLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new GoogleCloudLoggingPlugin({
+      logName: "projects/my-project/logs/my-api",
+      serviceAccountJson: environment.GCP_SERVICE_ACCOUNT,
+      fields: {
+        field1: "value1",
+        field2: "value2",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `GoogleCloudLoggingPlugin` constructor accepts an options object with the
+following properties:
+
+- `serviceAccountJson` - (required) The JSON content of your Google Cloud
+  service account key
+- `logName` - (required) The name of the log in Google Cloud Logging (for
+  example, `projects/my-project/logs/my-api`)
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+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.
+
+## Default Fields
+
+Every log entry will have a `timestamp` and a `jsonPayload` object. The value of
+the `jsonPayload` contains the text or objects passed into the log.
+
+Default fields in the `jsonPayload` are:
+
+- `severity` - The log level (for example, `ERROR`, `INFO`, `DEBUG`, `WARN`)
+- `requestId` - The UUID of the request (the value of the `zp-rid` header)
+- `environmentType` - Where the Zuplo API is running. Values are `edge`,
+  `working-copy`, or `local`
+- `environmentStage` - The environment stage: `working-copy`, `preview`, or
+  `production`
+- `atomicCounter` - An atomic counter used to order logs with identical
+  timestamps
+- `environment` - The environment name of the Zuplo API
+- `rayId` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request

package/docs/articles/log-plugin-loki.mdx

@@ -0,0 +1,136 @@
+---
+title: Loki Logging Plugin
+sidebar_label: Loki Logging
+---
+
+The Loki Log plugin enables pushing logs to your Loki server.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the Loki logging plugin to your Zuplo project, add the following code to
+your `zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  LokiLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new LokiLoggingPlugin({
+      // This is the URL of your Loki server
+      url: "https://logs-prod-us-central1.grafana.net/loki/api/v1/push",
+      username: "my-username",
+      job: "my-api",
+      password: environment.LOKI_PASSWORD,
+      version: 2,
+      fields: {
+        field1: "value1",
+        field2: "value2",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `LokiLoggingPlugin` constructor accepts an options object with the following
+properties:
+
+- `url` - (required) The URL of the Loki server (for example,
+  `https://logs-prod-us-central1.grafana.net/loki/api/v1/push`)
+- `username` - (required) Username for authentication
+- `password` - (required) Password for authentication
+- `version` - (optional) The version of the Loki transport to use. Version 2
+  includes tracing information in log values
+- `job` - (optional) Job name to include in the log stream. Defaults to "zuplo"
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+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.
+
+### Version Configuration
+
+Setting the `version` option to `2` changes the log stream to not include the
+`requestId` value in the stream, but rather include it as a log value with other
+tracing information.
+
+## Default Fields
+
+Every log entry will have a timestamp and structured data. The structure varies
+based on the version configuration.
+
+### Stream Labels (all versions)
+
+- `job` - The name of the log stream job. Defaults to "zuplo"
+- `level` - The log level (for example, `ERROR`, `INFO`, `DEBUG`, `WARN`)
+- `environmentType` - Where the Zuplo API is running. Values are `edge`,
+  `working-copy`, or `local`
+- `environmentStage` - The deployment stage: `working-copy`, `preview`, or
+  `production`
+
+### Log Fields (version 2+)
+
+When using version 2 or later, the following fields are included in the log
+values:
+
+- `requestId` - The UUID of the request (the value of the `zp-rid` header)
+- `atomicCounter` - An atomic counter used to order logs with identical
+  timestamps
+- `rayId` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request
+
+:::note
+
+Log trace fields are only included in the log values when the `version` option
+is set to `2` or later. In version 1, `requestId` is included as a stream label.
+
+:::
+
+## Log Format
+
+The shape of the logs sent from Zuplo will be in the following format. If using
+version 2, tracing info (`requestId`, etc.) will be included in the log values.
+
+```json
+{
+  "streams": [
+    {
+      "stream": {
+        "job": "zuplo",
+        "level": "debug",
+        "environmentType": "local",
+        "environmentStage": "local"
+      },
+      "values": [
+        [
+          "1712254635666000000",
+          "Request received '/hello-world'",
+          {
+            "requestId": "9b9cd3fd-b0fa-455f-b894-4a5c2c9d131b",
+            "rayId": "1235567",
+            "atomicCounter": 123435346
+          }
+        ],
+        [
+          "1712254635666000000",
+          "{\"method\":\"GET\",\"url\":\"/hello-world\",\"hostname\":\"localhost\",\"route\":\"/hello-world\"}",
+          {
+            "requestId": "9b9cd3fd-b0fa-455f-b894-4a5c2c9d131b",
+            "rayId": "1235567",
+            "atomicCounter": 123435347
+          }
+        ]
+      ]
+    }
+  ]
+}
+```

package/docs/articles/log-plugin-new-relic.mdx

@@ -0,0 +1,84 @@
+---
+title: New Relic Plugin
+sidebar_label: New Relic Logging
+---
+
+The New Relic Log plugin enables pushing logs to New Relic.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the New Relic logging plugin to your Zuplo project, add the following
+code to your `zuplo.runtime.ts` file.
+
+```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",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `NewRelicLoggingPlugin` constructor accepts an options object with the
+following properties:
+
+- `apiKey` - (required) Your New Relic API key for authentication
+- `url` - (optional) The New Relic logs API endpoint. Defaults to
+  "https://log-api.newrelic.com/log/v1"
+- `service` - (optional) Service name to identify the source of the logs.
+  Defaults to "Zuplo"
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+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.
+
+## Default Fields
+
+Every log entry will include the following fields (in snake_case format for New
+Relic):
+
+- `message` - The complete log message and data
+- `level` - The log level in lowercase (for example, `error`, `info`, `debug`,
+  `warn`)
+- `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` - The deployment stage: `working-copy`, `preview`, or
+  `production`
+- `request_id` - The UUID of the request (the value of the `zp-rid` header)
+- `atomic_counter` - An atomic counter used to order logs with identical
+  timestamps
+- `ray_id` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request
+- `log_source` - The source of the log entry
+
+:::note
+
+New Relic uses snake_case naming convention for field names and lowercase log
+levels.
+
+:::

package/docs/articles/log-plugin-splunk.mdx

@@ -0,0 +1,104 @@
+---
+title: Splunk Plugin (Beta)
+sidebar_label: Splunk Logging
+---
+
+The Splunk Log plugin enables pushing logs to Splunk using the HTTP Event
+Collector (HEC).
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the Splunk logging plugin to your Zuplo project, add the following code
+to your `zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  SplunkLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new SplunkLoggingPlugin({
+      // This is the URL of your Splunk HTTP Event Collector (HEC) endpoint
+      url: "https://<your-instance>.splunkcloud.com:8088/services/collector",
+      token: environment.SPLUNK_TOKEN,
+      // Channel ID for Splunk HEC with indexer acknowledgment
+      channel: "FE0ECFAD-13D5-401B-847D-77833BD77131",
+      // Optional parameters with defaults
+      index: "main",
+      sourcetype: "json",
+      host: "zuplo-api",
+      fields: {
+        environment: "production",
+        application: "my-api",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `SplunkLoggingPlugin` constructor accepts an options object with the
+following properties:
+
+- `url` - (required) The URL for the Splunk HTTP Event Collector (HEC) endpoint
+  - For self-hosted: `https://<splunk-host>:8088/services/collector`
+  - For cloud: `https://<your-instance>.splunkcloud.com:8088/services/collector`
+  - For Splunk Cloud with HTTP inputs:
+    `https://http-inputs-<your-instance>.splunkcloud.com:8088/services/collector`
+- `token` - (required) The Splunk HEC token for authentication
+- `index` - (optional) The Splunk index to send logs to. Defaults to "main"
+- `sourcetype` - (optional) The source type of the logs. Defaults to "json"
+- `host` - (optional) The host identifier for the logs. Defaults to "zuplo-api"
+- `channel` - (optional) Channel identifier for Splunk HEC with indexer
+  acknowledgment. If not provided, the X-Splunk-Request-Channel header won't be
+  sent
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+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.
+
+## Default Fields
+
+Every log entry will be sent to Splunk with the following structure:
+
+### Event Metadata
+
+- `time` - The timestamp in seconds since epoch
+- `host` - The host identifier (configurable, defaults to "zuplo-api")
+- `source` - The source identifier
+- `sourcetype` - The source type (configurable, defaults to "json")
+- `index` - The Splunk index (configurable, defaults to "main")
+
+### Event Fields (in the `event` object)
+
+- `message` - The complete log message and data
+- `level` - The log level in lowercase (for example, `error`, `info`, `debug`,
+  `warn`)
+- `timestamp` - The time the log was created (in milliseconds since epoch)
+- `service` - The name of the service (defaults to "Zuplo")
+- `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` - The deployment stage: `working-copy`, `preview`, or
+  `production`
+- `request_id` - The UUID of the request (the value of the `zp-rid` header)
+- `atomic_counter` - An atomic counter used to order logs with identical
+  timestamps
+- `ray_id` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request
+- `log_source` - The source of the log entry
+
+:::note
+
+Splunk uses snake_case naming convention for field names within the event data.
+
+:::

package/docs/articles/log-plugin-sumo.mdx

@@ -0,0 +1,73 @@
+---
+title: SumoLogic Plugin
+sidebar_label: SumoLogic Logging
+---
+
+The SumoLogic Log plugin enables pushing logs to SumoLogic.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To add the SumoLogic logging plugin to your Zuplo project, add the following
+code to your `zuplo.runtime.ts` file.
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  RuntimeExtensions,
+  SumoLogicLoggingPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new SumoLogicLoggingPlugin({
+      // This is the Sumo Logic HTTP collector endpoint URL
+      url: "https://endpoint4.collection.sumologic.com/receiver/v1/http/XXXXXX",
+      fields: {
+        field1: "value1",
+        field2: "value2",
+      },
+    }),
+  );
+}
+```
+
+## Configuration Options
+
+The `SumoLogicLoggingPlugin` constructor accepts an options object with the
+following properties:
+
+- `url` - (required) The Sumo Logic HTTP collector endpoint URL
+- `name` - (optional) The name metadata field for Sumo Logic
+- `category` - (optional) The category metadata field for Sumo Logic
+- `fields` - (optional) Custom fields to include in each log entry. Can contain
+  string, number, or boolean values
+
+### Custom Fields
+
+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.
+
+## Default Fields
+
+Every log entry will include the following fields (in camelCase format):
+
+- `timestamp` - The time the log was created (ISO 8601 format)
+- `severity` - The log level (for example, `ERROR`, `INFO`, `DEBUG`, `WARN`)
+- `data` - The log message and any additional data
+- `environmentType` - Where the Zuplo API is running. Values are `edge`,
+  `working-copy`, or `local`
+- `environmentStage` - The deployment stage: `working-copy`, `preview`, or
+  `production`
+- `requestId` - The UUID of the request (the value of the `zp-rid` header)
+- `atomicCounter` - An atomic counter used to order logs with identical
+  timestamps
+- `rayId` - The network provider identifier (for example, Cloudflare Ray ID) of
+  the request
+
+:::note
+
+Sumo Logic uses camelCase naming convention for field names.
+
+:::