zuplo 7.11.7 → 7.11.9

package/docs/articles/logging.mdx

@@ -25,6 +25,30 @@ search, and filters for severity, status, method, and route. Live mode streams
 new entries as they arrive and pauses automatically, for example when you select
 a request to inspect it.
 
+Each request row shows the path the client called, such as `/users/42`. Hover
+the path to see the full URL and the route it matched, such as `/users/:id`.
+Select a request to open its details, which list:
+
+- **URL**: the full URL of the request, including the query string.
+- **Route Path**: the route in your OpenAPI file that handled the request.
+- **Properties**: any [custom log properties](#custom-log-properties) your code
+  set for the request.
+
+When your code calls another route with
+[`context.invokeRoute`](../programmable-api/zuplo-context.mdx#invokeroute), the
+called route gets a log row of its own with the same request ID. The viewer
+nests that row under the request that made the call and marks it **Subrequest**,
+so a request and its sub-requests read as one group even when their status codes
+differ.
+
+:::caution
+
+The log viewer shows the full URL of each request, including its query string.
+Don't pass secrets such as API keys or tokens as query parameters; send them in
+headers instead.
+
+:::
+
 Logs are also available at the account scope, so you can debug across every
 project in an account in one place. Open
 [**Observability → Logs**](https://portal.zuplo.com/+/account/observability/logs)
@@ -112,8 +136,10 @@ details.
 
 ## Custom Log Properties
 
-In addition to the default fields, you can also add custom fields to your logs.
-This can be done using the `context.log.setLogProperties!` method.
+In addition to the default fields, you can add custom properties to a request
+with the `context.log.setLogProperties!` method. Use them for values you want to
+see on the request, such as a tenant ID, a feature flag, or an experiment
+variant.
 
 ```ts
 import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
@@ -122,18 +148,52 @@ export default async function policy(
   request: ZuploRequest,
   context: ZuploContext,
 ) {
-  context.log.setLogProperties!({ customProperty: "value" });
+  context.log.setLogProperties!({
+    tenantId: "acme",
+    pricingExperiment: "variant-b",
+    cached: false,
+  });
   context.log.info("Hello World");
   return request;
 }
 ```
 
-These properties will be included in all subsequent log messages for that
-request. If the property already exists, it will be overwritten.
-
-The log properties will be exported in a format native to the plugin you are
-using. For example, in the case of the OpenTelemetry plugin, the properties will
-be included in the `attributes` field of the log record.
+Custom log properties show up in two places:
+
+- **Your logging plugins**: every log message for the request logged after the
+  call includes the properties. They're exported in a format native to the
+  plugin you use. For example, the OpenTelemetry plugin includes them in the
+  `attributes` field of the log record.
+- **The log viewer in the Zuplo Portal**: the request's details list the
+  properties in the **Properties** section. See
+  [Viewing logs in the portal](#viewing-logs-in-the-portal).
+
+Custom log properties work as follows:
+
+- Properties apply only to the request that sets them.
+- Values can be strings, numbers, or booleans.
+- Each call merges into the properties already set for the request. If a
+  property already exists, it's overwritten.
+- A per-request property overrides a static field with the same name from your
+  logging plugin's `fields` option, for plugins that have one.
+- A route called with
+  [`context.invokeRoute`](../programmable-api/zuplo-context.mdx#invokeroute)
+  starts with no custom log properties of its own, and its properties appear on
+  its own row in the log viewer, not on the calling request.
+
+To keep requests small in the log viewer, the following limits apply there. A
+property that breaks a limit is left out of the log viewer, or, for a value
+that's too long, truncated. Log messages sent to your logging plugins aren't
+limited this way.
+
+| Limit                  | Value            |
+| ---------------------- | ---------------- |
+| Properties per request | 64               |
+| Key length             | 128 characters   |
+| Value length           | 2,048 characters |
+
+The `!` in `setLogProperties!` is a TypeScript non-null assertion: the method is
+typed as optional on the logger, but it's always available on `context.log`.
 
 ## Performance Under High Load
 

package/docs/programmable-api/zuplo-context.mdx

@@ -115,6 +115,11 @@ context.log.warn(["a", "warning"]);
 context.log.error({ Oh: "my!" });
 ```
 
+To add properties to the request, use `context.log.setLogProperties`. They're
+included in every later log message for the request and shown in the request's
+details in the log viewer. See
+[Custom Log Properties](../articles/logging.mdx#custom-log-properties).
+
 ### `parentContext`
 
 Reference to the parent context when using `invokeRoute`. This property is
@@ -270,6 +275,10 @@ Invokes another route within the same Zuplo Gateway. This enables internal
 routing and composition of multiple routes. The invoked route runs with a new
 context that has `parentContext` set to the current context.
 
+The invoked route is logged as a sub-request: it gets a log row of its own with
+the same request ID, and the log viewer nests it under the calling request. See
+[Viewing logs in the portal](../articles/logging.mdx#viewing-logs-in-the-portal).
+
 ```ts
 export default async function (request: ZuploRequest, context: ZuploContext) {
   // First, validate the request using an internal route

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuplo",
-  "version": "7.11.7",
+  "version": "7.11.9",
   "type": "module",
   "description": "The official Zuplo CLI for local development and platform management",
   "homepage": "https://zuplo.com/docs/cli/overview",
@@ -32,9 +32,9 @@
     "zuplo": "zuplo.js"
   },
   "dependencies": {
-    "@zuplo/cli": "7.11.7",
-    "@zuplo/core": "7.11.7",
-    "@zuplo/runtime": "7.11.7",
-    "@zuplo/test": "7.11.7"
+    "@zuplo/cli": "7.11.9",
+    "@zuplo/core": "7.11.9",
+    "@zuplo/runtime": "7.11.9",
+    "@zuplo/test": "7.11.9"
   }
 }