zuplo 6.71.3 → 6.71.6

package/docs/articles/graphql.mdx

@@ -8,27 +8,25 @@ tags:
   - backends
 ---
 
-Zuplo fronts a GraphQL API like any other backend: requests pass through a
-gateway route with the policies you attach, and your Dev Portal documents the
-schema. This guide proxies the endpoint, reports failed operations to analytics,
-and publishes a schema reference and playground.
+Zuplo has rich support for GraphQL. Pass your requests through the gateway,
+attach policies, track operations with analytics, and publish documentation for
+your schema in the Dev Portal. This guide walks you through setting it up.
 
 :::tip{title="TL;DR"}
 
-- [ ] Proxy your GraphQL endpoint through a route with the URL Rewrite handler
-- [ ] Tag the route with the `x-graphql` extension so the Portal recognizes it
+- [ ] Proxy your GraphQL endpoint through a POST `/graphql` route with the URL
+      Rewrite handler
+- [ ] Tag the route with the `x-graphql` extension
 - [ ] Surface failed operations with the `graphql-analytics-outbound` policy
-- [ ] Publish a schema reference and playground with the `graphqlPlugin` for the
-      Developer Portal
+- [ ] Add the `graphqlPlugin` to the Developer Portal
 
 :::
 
 ## Add a GraphQL endpoint to your gateway
 
-Because GraphQL uses a single endpoint, the route uses the
-[URL Rewrite handler](../handlers/url-rewrite.mdx) — every request goes to
-exactly the upstream URL — rather than URL Forward, which appends the incoming
-path.
+Set up the route with a [URL Rewrite handler](../handlers/url-rewrite.mdx) and
+set the rewrite URL to your upstream GraphQL server (for example,
+`https://api.example.com/graphql`).
 
 ### Add a new GraphQL route
 
@@ -44,10 +42,8 @@ path.
 
    Click **Add** and select **GraphQL Endpoint**. This creates a `POST /graphql`
    route preconfigured with the URL Rewrite handler, a demo upstream, and the
-   [GraphQL Analytics policy](#report-failed-operations-to-analytics) for error
-   reporting. If `/graphql` is already taken, the Portal appends a short suffix
-   (for example `/graphql-b891`) — edit the path to whatever you prefer. GraphQL
-   routes show a **GraphQL** badge in the route list instead of an HTTP method.
+   [GraphQL Analytics policy](../policies/graphql-analytics-outbound.mdx) for
+   error reporting. GraphQL routes show a **GraphQL** badge in the route list.
 
 3. **Point it at your upstream**
 
@@ -111,78 +107,9 @@ disable introspection in production.
 
 :::
 
-## Report failed operations to analytics
-
-Failed GraphQL operations return `200 OK` with an `errors[]` array in the body
-(the Apollo Server and graphql-yoga convention). HTTP-level analytics read that
-`200` as a success, so those failures never show up on the
-[GraphQL analytics dashboard](../analytics/tabs/graphql.md).
-
-The **GraphQL Analytics** policy closes that gap. It reads each response body,
-counts the GraphQL errors, and classifies every one by its `extensions.code` —
-`syntax`, `validation`, `auth`, `timeout`, or `resolver` — so failed operations
-appear on the dashboard as failures, broken down by error class. The response
-passes through to the client unchanged.
-
-:::caution{title="Beta"}
-
-The GraphQL Analytics policy is in beta. You can use it today, but it may change
-in non-backward compatible ways before the final release.
-
-:::
-
-New GraphQL endpoints include this policy automatically — the
-[Add a new GraphQL route](#add-a-new-graphql-route) flow attaches a
-`graphql-analytics-outbound` policy to the route's `outbound` chain, so error
-reporting works out of the box. If you instead
-[marked an existing route as GraphQL](#mark-an-existing-route-as-graphql), add a
-`graphql-analytics-outbound` policy and reference it in that route's `outbound`
-list.
-
-Tune the policy by editing its `options` in `config/policies.json`. Out of the
-box it classifies the standard Apollo error codes — for example, it reports
-`GRAPHQL_VALIDATION_FAILED` as `validation` and `UNAUTHENTICATED` as `auth` —
-and falls back to `resolver` for anything it doesn't recognize:
-
-```json title="config/policies.json"
-{
-  "policies": [
-    {
-      "name": "graphql-analytics",
-      "policyType": "graphql-analytics-outbound",
-      "handler": {
-        "export": "GraphqlAnalyticsOutboundPolicy",
-        "module": "$import(@zuplo/runtime)",
-        "options": {
-          "errorCodeClassification": {
-            "RATE_LIMITED": "resolver",
-            "NOT_LOGGED_IN": "auth"
-          },
-          "defaultErrorClass": "resolver",
-          "logErrors": true
-        }
-      }
-    }
-  ]
-}
-```
-
-- `errorCodeClassification` — Maps custom `extensions.code` values your server
-  emits to an error class. Entries merge over, and win against, the built-in
-  Apollo code map. Defaults to none.
-- `defaultErrorClass` — The class for an error whose code is missing or
-  unrecognized. One of `syntax`, `validation`, `auth`, `timeout`, or `resolver`.
-  Defaults to `resolver`.
-- `logErrors` — When `true`, also writes a structured warning to the request log
-  — the message, code, and path of each error, capped at the first 10 — for
-  every errored response. Defaults to `false`.
-- `maxResponseBytes` — The largest response body, in bytes, the policy inspects.
-  Larger responses pass through unscanned, so any errors they carry go
-  unreported. Defaults to `5242880` (5 MiB).
-
-See the
+To fine-tune analytics, see the
 [GraphQL Analytics policy reference](../policies/graphql-analytics-outbound.mdx)
-for the full classification table and schema.
+for the full set of options.
 
 ## Document the API in your Dev Portal
 
@@ -190,128 +117,46 @@ The `@zudoku/plugin-graphql` package renders a browsable type reference and a
 playground in your Dev Portal, generated from your schema. Register one instance
 per API.
 
-:::caution{title="Beta"}
-
-The GraphQL plugin is in beta.
-
-:::
-
-<Stepper>
+Import `graphqlPlugin` and add an instance per API. The `path` is where the docs
+mount, and `schema` points at your GraphQL API — either a live endpoint URL or a
+path to a schema definition language (SDL) file. Define the `path` once with
+`createPath` (a helper exported from `zudoku`) and reference the same value from
+both the plugin and the navigation link, so the link can never point at a path
+the plugin isn't mounted at:
 
-1. **Register the plugin**
-
-   Import `graphqlPlugin` and add an instance per API. The `path` is where the
-   docs mount, and `input` points at your GraphQL endpoint:
-
-   ```tsx title="zudoku.config.tsx"
-   import { graphqlPlugin } from "@zudoku/plugin-graphql";
-
-   const config = {
-     plugins: [
-       graphqlPlugin({
-         type: "url",
-         input: "https://graphql.example.com/api",
-         path: "/graphql/ecommerce",
-         options: {
-           title: "E-Commerce GraphQL API",
-           description: "Products, orders, and customers.",
-         },
-       }),
-     ],
-   };
-
-   export default config;
-   ```
-
-   With `type: "url"`, the portal fetches the schema via introspection at build
-   time, and the playground sends operations to that same URL by default. Point
-   `input` at the gateway route from the first half of this guide so readers run
-   real queries through your gateway — or keep the playground separate from the
-   schema source with `options.playground.endpoint`.
-
-   Have a GraphQL schema definition language (SDL) file instead of a live
-   endpoint? Use `type: "file"` and set `input` to the file's path (for example
-   `./schema.graphql`). A file-based schema doesn't tell the plugin where your
-   API lives, so also set `options.playground.endpoint` — without it the
-   reference pages still render, but the playground asks for an endpoint before
-   it can run operations.
-
-   You can register the plugin more than once to document several schemas, each
-   with its own `path`.
-
-   :::note
-
-   New projects ship with `@zudoku/plugin-graphql` in `dependencies` already.
-   Older projects might need to add it to `docs/package.json`. The plugin
-   requires `zudoku` version `0.80.1` or newer.
-   [Update the Dev Portal](../dev-portal/updating.mdx) to get the latest
-   version.
-
-   :::
-
-2. **Link it in the navigation**
-
-   Point a navigation link at the instance's `path`. Set `stack: true` so the
-   API's own pages render as a stacked sub-navigation instead of expanding
-   inline:
-
-   ```tsx title="zudoku.config.tsx"
-   navigation: [
-     {
-       type: "category",
-       label: "Documentation",
-       items: [
-         {
-           type: "link",
-           label: "E-Commerce API",
-           to: "/graphql/ecommerce",
-           stack: true,
-         },
-       ],
-     },
-   ];
-   ```
-
-   Prefer the API as its own top-level section instead? Drop the link at the top
-   level of `navigation` and leave off `stack`. See the
-   [navigation reference](../dev-portal/zudoku/configuration/navigation.mdx) for
-   all link, category, and stacking options.
+```tsx title="zudoku.config.tsx"
+import { graphqlPlugin } from "@zudoku/plugin-graphql";
+import { createPath } from "zudoku";
 
-</Stepper>
+const graphqlPath = createPath("/graphql");
 
-### Plugin options
-
-All options live under the instance's `options` key:
+const config = {
+  navigation: [
+    {
+      type: "link",
+      label: "GraphQL API",
+      to: graphqlPath,
+    },
+  ],
+  plugins: [
+    graphqlPlugin({
+      schema: "./schema.graphql", // Also accepts a URL, e.g. https://...
+      path: graphqlPath,
+    }),
+  ],
+};
+
+export default config;
+```
 
-| Option                | Type      | Description                                                                                                                                            |
-| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `title`               | `string`  | Display title for the API's overview page.                                                                                                             |
-| `description`         | `string`  | Short description shown on the overview page.                                                                                                          |
-| `showDeprecated`      | `boolean` | Include deprecated fields and operations in the reference.                                                                                             |
-| `playground.enabled`  | `boolean` | Show the playground. Defaults to `true`.                                                                                                               |
-| `playground.endpoint` | `string`  | URL the playground sends operations to. Defaults to `input` for `type: "url"`. File schemas have no default; the playground prompts for one until set. |
-| `playground.headers`  | `object`  | Default headers the playground sends with each operation.                                                                                              |
+You can register the plugin more than once to document several schemas, each
+with its own `path`.
 
 ## Verify it worked
 
-Open the
-[**Environments**](https://portal.zuplo.com/+/account/project/environments) tab
-in the Zuplo Portal — your build is listed there along with the URLs for both
-your gateway and your Dev Portal. Send a query through the gateway URL:
-
-```bash
-curl https://my-gateway.example.com/graphql \
-  -H "Content-Type: application/json" \
-  -d '{"query":"{ __typename }"}'
-```
-
-A working route returns a response from your upstream, such as
-`{"data":{"__typename":"Query"}}`.
-
-For the Dev Portal, open its URL from the **Environments** tab (or run
-`npm run dev` in your `docs/` folder) and go to the plugin's `path` (for example
-`/graphql/ecommerce`). The overview page lists the schema's types, and the
-playground runs operations against your configured endpoint.
+Open your Dev Portal, navigate to the GraphQL API, and run a query in the
+playground. A successful response confirms the gateway is proxying requests and
+the playground is pointed at the right endpoint.
 
 ## Next steps
 

package/docs/articles/opentelemetry.mdx

@@ -3,28 +3,22 @@ title: Zuplo OpenTelemetry
 sidebar_label: OpenTelemetry
 ---
 
-Zuplo ships with an OpenTelemetry plugin that allows you to collect and export
-telemetry data from your Zuplo API. The OpenTelemetry plugin supports tracing
-and logging. Metrics support is planned for future releases.
+Zuplo ships with an OpenTelemetry plugin (`@zuplo/otel`) that instruments your
+API and exports traces and logs in OpenTelemetry format. The quickest way to use
+it is Zuplo's built-in tracing: add the plugin and your traces are stored by
+Zuplo and shown in the portal's **Observability** tab, with no collector to run
+or backend to host. You can also export to your own OpenTelemetry backend, or to
+both at once.
 
 <EnterpriseFeature name="OpenTelemetry" />
 
 ## Tracing
 
-Tracing enables you to monitor performance, identify bottlenecks, and
-troubleshoot issues in your Zuplo API. The OpenTelemetry plugin automatically
-instruments your API to collect trace data. You can send trace data any
-OpenTelemetry service such as [Honeycomb](https://honeycomb.io),
-[Middleware](https://middleware.io/), [Dynatrace](https://dynatrace.com),
-[Jaeger](https://www.jaegertracing.io/), and
-[many more](https://opentelemetry.io/ecosystem/).
-
-With tracing enabled on your Zuplo API you will see timings for each request as
-well as spans for plugins, handlers, and policies. The OpenTelemetry plugin
-supports trace propagation (W3C headers by default) so you can trace requests
-all the way from the client to your backend.
-
-![Trace visualization](../../public/media/opentelemetry/image-1.png)
+Tracing helps you monitor performance, identify bottlenecks, and troubleshoot
+issues in your Zuplo API. The OpenTelemetry plugin automatically instruments
+your API, so you get timings for each request along with spans for policies,
+handlers, and subrequests. It supports trace propagation (W3C headers by
+default), so you can follow a request from the client through to your backend.
 
 ### What's Traced?
 
@@ -34,114 +28,65 @@ By default, when the OpenTelemetry plugin is enabled, the following is traced:
   process the request and send the response.
 - Inbound Policies: The time taken to execute all inbound policies as well as
   each policy is traced.
-- Handler: The request handler is traced
+- Handler: The request handler is traced.
 - Outbound Policies: The time taken to execute all outbound policies as well as
   each policy is traced.
-- Subrequests: Any use of `fetch` within your custom policies or handlers will
-  be traced.
+- Subrequests: Any use of `fetch` within your custom policies or handlers is
+  traced.
 
 ### Limitations
 
 One important limitation to keep in mind is that the clock will only increment
 when performing I/O operations (for example when calling `fetch`, using the
-Cache APIs, etc.). This is a limitation imposed as a security measure due
+Cache APIs, etc.). This is a limitation imposed as a security measure due to
 Zuplo's serverless, multi-tenant architecture. In practice this shouldn't impact
-your ability to trace as virtually any code that isn't I/O bound is fast.
+your ability to trace, as virtually any code that isn't I/O bound is fast.
 
-### Custom Tracing
+## Setup
 
-You can add custom tracing to your Zuplo API by using the OpenTelemetry API. The
-example below shows how to implement tracing in a custom policy.
+Add the `OpenTelemetryPlugin` in your `zuplo.runtime.ts` file. Where it sends
+data is up to you: Zuplo's built-in storage, your own backend, or both.
 
-```ts
-import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
-import { trace } from "@opentelemetry/api";
+### Send Traces to Zuplo
 
-export default async function policy(
-  request: ZuploRequest,
-  context: ZuploContext,
-) {
-  const tracer = trace.getTracer("my-tracer");
-  return tracer.startActiveSpan("my-span", async (span) => {
-    span.setAttribute("key", "value");
+Add the plugin with no configuration. It sends traces to Zuplo and names the
+service after your project:
 
-    try {
-      const results = await Promise.all([
-        fetch("https://api.example.com/hello"),
-        fetch("https://api.example.com/world"),
-      ]);
-      // ...
+```ts title="zuplo.runtime.ts"
+import { OpenTelemetryPlugin } from "@zuplo/otel";
+import { RuntimeExtensions } from "@zuplo/runtime";
 
-      return request;
-    } finally {
-      span.end();
-    }
-  });
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(new OpenTelemetryPlugin());
 }
 ```
 
-This will result in a span that has the following spans:
-
-```txt
-|--- my-policy
-|    |
-|    |--- my-span
-|    |    |
-|    |    |--- GET https://api.example.com/hello
-|    |    |
-|    |    |--- GET https://api.example.com/world
-```
-
-## Logging
+Deploy your project and open the **Observability** tab to see traces.
 
-Logging can be enabled by configuring the `logUrl` property in the OpenTelemetry
-plugin configuration, as shown in
-[Tracing and Logging Configuration](#tracing-and-logging-configuration). When
-enabled, logs will be exported to the specified endpoint in OpenTelemetry
-format.
-
-To add OpenTelemetry logs in your Zuplo handlers and policies, you can use the
-`context.log` object as shown below:
-
-```ts
-import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
-
-export default async function policy(
-  request: ZuploRequest,
-  context: ZuploContext,
-) {
-  context.log.info("Hello World");
-  return request;
-}
-```
-
-You can also set additional custom log properties using
-`context.log.setLogProperties!`:
+![Trace visualization](../../public/media/opentelemetry/image-1.png)
 
-```ts
-import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+Each trace is tagged with the account, project, deployment, and environment it
+ran in, plus the request ID (the `zp-rid` value) that also appears on your
+[logs](#logging), so you can move between a request's logs and its trace. How
+long traces are kept depends on your plan.
 
-export default async function policy(
-  request: ZuploRequest,
-  context: ZuploContext,
-) {
-  context.log.setLogProperties!({ customProperty: "value" });
-  context.log.info("Hello World");
-  return request;
-}
-```
+:::note
 
-After setting a custom property, all subsequent log messages will include that
-property.
+Traces reach Zuplo only from deployed environments. During local development
+(`zuplo dev`) there is no Zuplo ingest to send to, so the plugin logs a startup
+warning and skips the Zuplo destination. Any other destinations you configure
+still run.
 
-These logs will be exported to the configured log endpoint in OpenTelemetry
-format. The log message will be in the `message` field and the custom properties
-will be in the `attributes` field.
+:::
 
-## Setup
+### Export to Your Own Backend
 
-Adding OpenTelemetry to your Zuplo API is done by adding the
-`OpenTelemetryPlugin` in the `zuplo.runtime.ts` file as shown below.
+To send traces to an OpenTelemetry service such as
+[Honeycomb](https://honeycomb.io), [Middleware](https://middleware.io/),
+[Dynatrace](https://dynatrace.com), [Jaeger](https://www.jaegertracing.io/), or
+[others](https://opentelemetry.io/ecosystem/), configure an `exporter` with the
+service's `url` and `headers`. It's common for providers to use a header for
+authorization. Configuring an `exporter` sends traces there instead of Zuplo.
 
 :::warning{title="OpenTelemetry Protocol"}
 
@@ -153,11 +98,6 @@ convert the JSON format to the format required by your service.
 
 :::
 
-### Basic Tracing Configuration
-
-For most providers you will set values for `exporter.url` and
-`exporter.headers`. It's common for providers to use a header for authorization.
-
 ```ts title="zuplo.runtime.ts"
 import { OpenTelemetryPlugin } from "@zuplo/otel";
 import { RuntimeExtensions, environment } from "@zuplo/runtime";
@@ -180,10 +120,10 @@ export function runtimeInit(runtime: RuntimeExtensions) {
 }
 ```
 
-### Advanced Tracing Configuration
+#### Sampling and Post-Processing
 
-The OpenTelemetry plugin supports additional configuration options for advanced
-use cases, including sampling and post-processing of spans.
+The plugin supports additional options for advanced use cases, including head
+sampling and post-processing of spans before export.
 
 ```ts title="zuplo.runtime.ts"
 import { OpenTelemetryPlugin } from "@zuplo/otel";
@@ -219,14 +159,13 @@ export function runtimeInit(runtime: RuntimeExtensions) {
 }
 ```
 
-### Tracing and Logging Configuration
+#### Logs and Traces Together
 
-Logging is only enabled when specifically configured with its own endpoint using
-the `logUrl` property. When using both tracing and logging, use the top-level
-`traceUrl`, `logUrl`, and `headers` properties instead of the `exporter` object
-shown above. The plugin supports both configuration shapes, but they're mutually
-exclusive: `exporter` configures tracing only, while `traceUrl` and `logUrl`
-configure tracing and logging together with a shared set of `headers`.
+To export logs as well as traces, use the top-level `traceUrl`, `logUrl`, and
+`headers` properties instead of the `exporter` object. The plugin supports both
+shapes, but they're mutually exclusive: `exporter` configures tracing only,
+while `traceUrl` and `logUrl` configure tracing and logging together with a
+shared set of `headers`. See [Logging](#logging) for how to emit log records.
 
 ```ts title="zuplo.runtime.ts"
 import { OpenTelemetryPlugin } from "@zuplo/otel";
@@ -251,3 +190,124 @@ export function runtimeInit(runtime: RuntimeExtensions) {
   );
 }
 ```
+
+### Send Traces to Zuplo and Your Own Backend
+
+You aren't limited to one destination. To deliver traces to Zuplo and your own
+backend at the same time, add a span processor for each. Zuplo is represented by
+a `ZuploSpanExporter`. The processors batch and flush independently, so a slow
+or failing backend doesn't hold up the other:
+
+```ts title="zuplo.runtime.ts"
+import {
+  OpenTelemetryPlugin,
+  OTLPSpanExporter,
+  BatchTraceSpanProcessor,
+  ZuploSpanExporter,
+} from "@zuplo/otel";
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OpenTelemetryPlugin({
+      service: { name: "my-api" },
+      spanProcessors: [
+        new BatchTraceSpanProcessor(
+          new OTLPSpanExporter({
+            url: "https://otel-collector.example.com/v1/traces",
+            headers: { "api-key": environment.OTEL_API_KEY },
+          }),
+        ),
+        new BatchTraceSpanProcessor(new ZuploSpanExporter()),
+      ],
+    }),
+  );
+}
+```
+
+## Logging
+
+The plugin can also export logs in OpenTelemetry format. Logs are sent to your
+own endpoint configured with the `logUrl` property (see
+[Logs and Traces Together](#logs-and-traces-together)); Zuplo's built-in storage
+covers traces today, with managed logs and metrics planned for future releases.
+
+To emit OpenTelemetry logs from your handlers and policies, use the
+`context.log` object:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  context.log.info("Hello World");
+  return request;
+}
+```
+
+You can also set additional custom log properties using
+`context.log.setLogProperties!`:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  context.log.setLogProperties!({ customProperty: "value" });
+  context.log.info("Hello World");
+  return request;
+}
+```
+
+After setting a custom property, all subsequent log messages will include that
+property. These logs are exported to the configured log endpoint in
+OpenTelemetry format: the log message is in the `message` field and the custom
+properties are in the `attributes` field.
+
+## Custom Tracing
+
+You can add custom tracing to your Zuplo API using the OpenTelemetry API. The
+example below shows how to implement tracing in a custom policy.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import { trace } from "@opentelemetry/api";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const tracer = trace.getTracer("my-tracer");
+  return tracer.startActiveSpan("my-span", async (span) => {
+    span.setAttribute("key", "value");
+
+    try {
+      const results = await Promise.all([
+        fetch("https://api.example.com/hello"),
+        fetch("https://api.example.com/world"),
+      ]);
+      // ...
+
+      return request;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+This will result in the following spans:
+
+```txt
+|--- my-policy
+|    |
+|    |--- my-span
+|    |    |
+|    |    |--- GET https://api.example.com/hello
+|    |    |
+|    |    |--- GET https://api.example.com/world
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "6.71.3",
+  "version": "6.71.6",
   "type": "module",
   "description": "The programmable API Gateway",
   "author": "Zuplo, Inc.",
@@ -19,9 +19,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "6.71.3",
-    "@zuplo/core": "6.71.3",
-    "@zuplo/runtime": "6.71.3",
+    "@zuplo/cli": "6.71.6",
+    "@zuplo/core": "6.71.6",
+    "@zuplo/runtime": "6.71.6",
     "@zuplo/test": "1.4.0"
   }
 }