From 294e6826511558347bb42f61feeacfc2013f7ff8 Mon Sep 17 00:00:00 2001 From: Alex Luong Date: Wed, 21 Oct 2026 23:50:49 +0700 Subject: [PATCH 1/3] docs: add v1.7 upgrade guide --- docs/content/nav.json | 4 ++ .../self-hosting/changelog/upgrade-v1.7.mdoc | 40 +++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/content/self-hosting/changelog/upgrade-v1.7.mdoc diff --git a/docs/content/nav.json b/docs/content/nav.json index 6d4f35a66..05cc12e43 100644 --- a/docs/content/nav.json +++ b/docs/content/nav.json @@ -243,6 +243,10 @@ "label": "Changelog", "sections": [ [ + { + "slug": "self-hosting/changelog/upgrade-v1.7", + "title": "Upgrade to v1.7" + }, { "slug": "self-hosting/changelog/upgrade-v1.6", "title": "Upgrade to v1.6" diff --git a/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc b/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc new file mode 100644 index 000000000..2534b90e5 --- /dev/null +++ b/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc @@ -0,0 +1,40 @@ +--- +title: "Upgrade to v1.7" +description: "Breaking changes and behavior changes when upgrading Outpost from v1.6 to v1.7." +--- + +This guide covers what changes when upgrading from v1.6 to v1.7. There is one breaking change and several behavior changes to review before upgrading. + +There are no new PostgreSQL or ClickHouse migrations. Upgrade by replacing the image in place, with no extra steps. Retries scheduled by v1.6 run normally on v1.7, and you can roll back to v1.6.0 the same way. + +| Change | Impact | Action Required | +| --- | --- | --- | +| [Redis and message queue OpenTelemetry instrumentation is off by default](#redis-and-message-queue-opentelemetry-instrumentation-is-off-by-default) | Deployments that export OpenTelemetry traces or metrics | Set `OTEL_ENABLED_INSTRUMENTATIONS=redis,mq` to keep them | + +For new features and fixes, see the [v1.7.0 release notes](https://github.com/hookdeck/outpost/releases/tag/v1.7.0). + +## Breaking Changes + +### Redis and message queue OpenTelemetry instrumentation is off by default + +Outpost no longer exports Redis command spans or internal message queue client spans and metrics. Other traces and metrics are unchanged. + +To export them again, set `OTEL_ENABLED_INSTRUMENTATIONS=redis,mq`, or only one of the two values, for example `OTEL_ENABLED_INSTRUMENTATIONS=redis`. See [Observability](/docs/outpost/self-hosting/configuration#observability). + +## Behavior Changes + +- Retry delays shorter than `LOG_BATCH_THRESHOLD_SECONDS` (default `10`) are raised to it. Outpost logs a warning at startup that lists the affected delays. See [Automatic retries](/docs/outpost/features/event-delivery#automatic-retries). +- At most `RETRY_MAX_CONCURRENCY` retries (default `100`) start at once per process. v1.6 had no limit; set it to `0` to keep it that way. +- A tenant JWT with a `deployment_id` claim that differs from `DEPLOYMENT_ID`, or that has the claim when `DEPLOYMENT_ID` is not set, is rejected with `401`. Tokens without the claim, and tokens with a matching claim, still work. +- A path or query parameter containing a NUL character or invalid UTF-8 returns `400`, where the PostgreSQL log store returned `500`. + +## New Configuration + +See the [configuration reference](/docs/outpost/self-hosting/configuration) for defaults and details. + +- [`RETRY_MAX_CONCURRENCY`](/docs/outpost/self-hosting/configuration#delivery): limit concurrent retry starts. +- [`RETRY_MAX_RECEIVE_COUNT`](/docs/outpost/self-hosting/configuration#delivery): failed retry starts before the retry moves to the dead-letter queue. v1.6 fixed this at `5`, which stays the default. +- [`RETRY_LOOKUP_BATCH_SIZE`](/docs/outpost/self-hosting/configuration#delivery) and `RETRY_LOOKUP_BATCH_WAIT_MS`: combine retry lookups into fewer log store queries. Off by default. +- [`CLICKHOUSE_MAX_OPEN_CONNS`](/docs/outpost/self-hosting/configuration#log-storage), `CLICKHOUSE_DIAL_TIMEOUT_SECONDS` and `CLICKHOUSE_READ_TIMEOUT_SECONDS`: ClickHouse connection pool size and timeouts. +- [`OTEL_ENABLED_INSTRUMENTATIONS`](/docs/outpost/self-hosting/configuration#observability): opt in to Redis and message queue instrumentation. +- [`DESTINATIONS_WEBHOOK_TIMESTAMP_FORMAT`](/docs/outpost/self-hosting/configuration#webhook-behavior) accepts `iso8601_milli_no_offset`. From 4fd7ce871ea985c925c6c9d52b57f74de51c0ffe Mon Sep 17 00:00:00 2001 From: Alex Luong Date: Fri, 23 Oct 2026 21:42:42 +0700 Subject: [PATCH 2/3] docs: tighten v1.7 upgrade guide --- .../content/self-hosting/changelog/upgrade-v1.7.mdoc | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc b/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc index 2534b90e5..62285880a 100644 --- a/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc +++ b/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc @@ -17,15 +17,17 @@ For new features and fixes, see the [v1.7.0 release notes](https://github.com/ho ### Redis and message queue OpenTelemetry instrumentation is off by default -Outpost no longer exports Redis command spans or internal message queue client spans and metrics. Other traces and metrics are unchanged. +With OpenTelemetry enabled, Outpost no longer exports Redis command spans or internal message queue client spans and metrics. Outpost's own traces and metrics and the HTTP server spans are unchanged. Without `OTEL_SERVICE_NAME` set, nothing changes. -To export them again, set `OTEL_ENABLED_INSTRUMENTATIONS=redis,mq`, or only one of the two values, for example `OTEL_ENABLED_INSTRUMENTATIONS=redis`. See [Observability](/docs/outpost/self-hosting/configuration#observability). +To export them again, set `OTEL_ENABLED_INSTRUMENTATIONS=redis,mq`, or only one of the two values, for example `OTEL_ENABLED_INSTRUMENTATIONS=redis`. Any other value fails startup. See [Observability](/docs/outpost/self-hosting/configuration#observability). + +The GCP Pub/Sub destination's gRPC spans and metrics are no longer exported either, and no setting turns them back on. ## Behavior Changes -- Retry delays shorter than `LOG_BATCH_THRESHOLD_SECONDS` (default `10`) are raised to it. Outpost logs a warning at startup that lists the affected delays. See [Automatic retries](/docs/outpost/features/event-delivery#automatic-retries). +- Retry delays shorter than `LOG_BATCH_THRESHOLD_SECONDS` (default `10`) are raised to it. This affects `RETRY_SCHEDULE` steps and a `RETRY_INTERVAL_SECONDS` below it; the default schedule (30 second base) is unchanged. Outpost logs a warning at startup that lists the affected delays. See [Automatic retries](/docs/outpost/features/event-delivery#automatic-retries). - At most `RETRY_MAX_CONCURRENCY` retries (default `100`) start at once per process. v1.6 had no limit; set it to `0` to keep it that way. -- A tenant JWT with a `deployment_id` claim that differs from `DEPLOYMENT_ID`, or that has the claim when `DEPLOYMENT_ID` is not set, is rejected with `401`. Tokens without the claim, and tokens with a matching claim, still work. +- A tenant JWT whose `deployment_id` claim doesn't match `DEPLOYMENT_ID` is rejected with `401`. - A path or query parameter containing a NUL character or invalid UTF-8 returns `400`, where the PostgreSQL log store returned `500`. ## New Configuration @@ -35,6 +37,6 @@ See the [configuration reference](/docs/outpost/self-hosting/configuration) for - [`RETRY_MAX_CONCURRENCY`](/docs/outpost/self-hosting/configuration#delivery): limit concurrent retry starts. - [`RETRY_MAX_RECEIVE_COUNT`](/docs/outpost/self-hosting/configuration#delivery): failed retry starts before the retry moves to the dead-letter queue. v1.6 fixed this at `5`, which stays the default. - [`RETRY_LOOKUP_BATCH_SIZE`](/docs/outpost/self-hosting/configuration#delivery) and `RETRY_LOOKUP_BATCH_WAIT_MS`: combine retry lookups into fewer log store queries. Off by default. -- [`CLICKHOUSE_MAX_OPEN_CONNS`](/docs/outpost/self-hosting/configuration#log-storage), `CLICKHOUSE_DIAL_TIMEOUT_SECONDS` and `CLICKHOUSE_READ_TIMEOUT_SECONDS`: ClickHouse connection pool size and timeouts. +- [`CLICKHOUSE_MAX_OPEN_CONNS`](/docs/outpost/self-hosting/configuration#log-storage), `CLICKHOUSE_DIAL_TIMEOUT_SECONDS` and `CLICKHOUSE_READ_TIMEOUT_SECONDS`: ClickHouse connection pool size and timeouts. The defaults match v1.6. - [`OTEL_ENABLED_INSTRUMENTATIONS`](/docs/outpost/self-hosting/configuration#observability): opt in to Redis and message queue instrumentation. - [`DESTINATIONS_WEBHOOK_TIMESTAMP_FORMAT`](/docs/outpost/self-hosting/configuration#webhook-behavior) accepts `iso8601_milli_no_offset`. From 8d1f27a1bfba067d5f0c7c9d870214b79f7cdba6 Mon Sep 17 00:00:00 2001 From: Alex Luong Date: Tue, 27 Oct 2026 20:18:22 +0700 Subject: [PATCH 3/3] docs: clarify v1.7 upgrade guide wording Co-Authored-By: Claude Opus 5.5 --- docs/content/self-hosting/changelog/upgrade-v1.7.mdoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc b/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc index 62285880a..e91eb7f59 100644 --- a/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc +++ b/docs/content/self-hosting/changelog/upgrade-v1.7.mdoc @@ -3,7 +3,7 @@ title: "Upgrade to v1.7" description: "Breaking changes and behavior changes when upgrading Outpost from v1.6 to v1.7." --- -This guide covers what changes when upgrading from v1.6 to v1.7. There is one breaking change and several behavior changes to review before upgrading. +This guide covers what changes when upgrading from v1.6 to v1.7. There is one breaking change and four behavior changes to review before upgrading. There are no new PostgreSQL or ClickHouse migrations. Upgrade by replacing the image in place, with no extra steps. Retries scheduled by v1.6 run normally on v1.7, and you can roll back to v1.6.0 the same way. @@ -17,7 +17,7 @@ For new features and fixes, see the [v1.7.0 release notes](https://github.com/ho ### Redis and message queue OpenTelemetry instrumentation is off by default -With OpenTelemetry enabled, Outpost no longer exports Redis command spans or internal message queue client spans and metrics. Outpost's own traces and metrics and the HTTP server spans are unchanged. Without `OTEL_SERVICE_NAME` set, nothing changes. +With OpenTelemetry enabled, Outpost no longer exports Redis command spans or internal message queue client spans and metrics. Outpost's own traces and metrics, and the HTTP server spans, are unchanged. Without `OTEL_SERVICE_NAME` set, nothing changes. To export them again, set `OTEL_ENABLED_INSTRUMENTATIONS=redis,mq`, or only one of the two values, for example `OTEL_ENABLED_INSTRUMENTATIONS=redis`. Any other value fails startup. See [Observability](/docs/outpost/self-hosting/configuration#observability). @@ -25,9 +25,9 @@ The GCP Pub/Sub destination's gRPC spans and metrics are no longer exported eith ## Behavior Changes -- Retry delays shorter than `LOG_BATCH_THRESHOLD_SECONDS` (default `10`) are raised to it. This affects `RETRY_SCHEDULE` steps and a `RETRY_INTERVAL_SECONDS` below it; the default schedule (30 second base) is unchanged. Outpost logs a warning at startup that lists the affected delays. See [Automatic retries](/docs/outpost/features/event-delivery#automatic-retries). +- Retry delays shorter than `LOG_BATCH_THRESHOLD_SECONDS` (default `10`) are raised to it. This affects `RETRY_SCHEDULE` steps and a `RETRY_INTERVAL_SECONDS` below it; the default retry timing (`RETRY_INTERVAL_SECONDS=30`) is unchanged. Outpost logs a warning at startup that lists the affected delays. See [Automatic retries](/docs/outpost/features/event-delivery#automatic-retries). - At most `RETRY_MAX_CONCURRENCY` retries (default `100`) start at once per process. v1.6 had no limit; set it to `0` to keep it that way. -- A tenant JWT whose `deployment_id` claim doesn't match `DEPLOYMENT_ID` is rejected with `401`. +- A tenant JWT whose `deployment_id` claim doesn't match `DEPLOYMENT_ID` is rejected with `401`. Tokens issued by Outpost and tokens without the claim keep working. - A path or query parameter containing a NUL character or invalid UTF-8 returns `400`, where the PostgreSQL log store returned `500`. ## New Configuration