feat(deploy): limit OpenObserve retention to 30 days

Author: thonatos

apps/api/test/telemetry-deployment-config.test.ts

@@ -38,6 +38,14 @@ describe("telemetry deployment configuration", () => {
     expect(collector).toContain("level: warn");
   });
 
+  test("retains OpenObserve telemetry for 30 days by default", () => {
+    const service = compose.split("\n  openobserve:")[1]?.split("\n  otel-collector:")[0] || "";
+    expect(service).toContain(
+      'ZO_COMPACT_DATA_RETENTION_DAYS: "${ZO_COMPACT_DATA_RETENTION_DAYS:-30}"',
+    );
+    expect(productionEnv).toContain("ZO_COMPACT_DATA_RETENTION_DAYS=30");
+  });
+
   test("routes applications only to the Collector", () => {
     expect(productionEnv).toContain(
       "CNODE_OTEL_EXPORTER_OTLP_BASE_ENDPOINT=http://otel-collector:4318",

docs/deployment/deployment.md

@@ -49,7 +49,7 @@ docker rm openobserve
 docker compose up -d --no-build openobserve
 ```
 
-OpenObserve uses `latest`. Before pulling an update, create and verify a restorable `openobserve-data` backup and record the current image ID. Its internal address is `http://openobserve:5080`; Compose does not publish that port.
+OpenObserve uses `latest`. Before pulling an update, create and verify a restorable `openobserve-data` backup and record the current image ID. Its internal address is `http://openobserve:5080`; Compose does not publish that port. `ZO_COMPACT_DATA_RETENTION_DAYS=30` applies one global 30-day retention period to logs, metrics, and traces. OpenObserve's compactor removes older data asynchronously, so disk usage does not drop immediately after restart. Never delete files directly from `openobserve-data`; increasing the retention value later cannot restore data already deleted by the compactor.
 
 ## Configure Application Telemetry
 

docs/deployment/docker-compose.yml

@@ -83,6 +83,8 @@ services:
   openobserve:
     image: public.ecr.aws/zinclabs/openobserve:latest
     env_file: ${CNODE_ENV_FILE:-.env}
+    environment:
+      ZO_COMPACT_DATA_RETENTION_DAYS: "${ZO_COMPACT_DATA_RETENTION_DAYS:-30}"
     volumes:
       - openobserve-data:/data
     healthcheck:

docs/deployment/env.production.example

@@ -70,6 +70,7 @@ CNODE_OTEL_TRACE_SAMPLE_RATIO=0.1
 # OpenObserve service
 ZO_ROOT_USER_EMAIL=admin@example.com
 ZO_ROOT_USER_PASSWORD=replace-with-openobserve-root-password
+ZO_COMPACT_DATA_RETENTION_DAYS=30
 
 # OpenTelemetry Collector
 OPENOBSERVE_OTLP_ENDPOINT=https://metrics.example.com/api/default

openspec/changes/archive/2026-08-12-set-openobserve-retention-30-days/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-11

openspec/changes/archive/2026-08-12-set-openobserve-retention-30-days/design.md

@@ -0,0 +1,61 @@
+## Context
+
+生产 OpenObserve 使用单节点、本地持久卷和 `latest` 镜像。当前部署未显式设置数据保留期，因此继承上游 `ZO_COMPACT_DATA_RETENTION_DAYS=3650`。应用现已持续导出 traces、logs 和 metrics，需要在 OpenObserve 进程边界设置统一、可审计的磁盘保留上限。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 将生产 OpenObserve 的全局默认数据保留期固定为 30 天。
+- 让 Compose、dotenv example、部署说明和自动化测试表达同一配置。
+- 通过重建 OpenObserve 使配置生效，并验证容器健康。
+
+**Non-Goals:**
+
+- 不配置 stream-level retention 或不同信号的独立期限。
+- 不同步删除数据卷文件，不承诺配置生效后立即释放磁盘。
+- 不修改应用 telemetry exporter 或 Collector pipeline。
+
+## Decisions
+
+### 使用 OpenObserve 全局 compactor retention 变量
+
+在 OpenObserve service environment 中传入 `ZO_COMPACT_DATA_RETENTION_DAYS`，Compose 默认值为 `30`，并在生产 dotenv example 中显式声明 `30`。官方将该变量定义为全局数据保留天数，最小值为 3，适用于 compactor 自动清理。
+
+备选方案是在 UI 中逐 stream 配置 retention。该方案容易遗漏新建 stream，且生产状态无法由仓库配置审计，因此不采用。
+
+### 允许 dotenv 覆盖但默认保持 30 天
+
+Compose 使用 `${ZO_COMPACT_DATA_RETENTION_DAYS:-30}`，使标准部署无需额外配置即可获得 30 天边界，同时保留紧急容量调整能力。部署说明要求任何覆盖都经过明确运维评估。
+
+备选方案是直接写死 `30`。该方案无法在不改 Compose 文件的情况下处理临时容量策略，因此不采用。
+
+### 依赖 compactor 异步清理
+
+配置仅通过 OpenObserve 支持的 retention 机制生效，不直接操作 `openobserve-data`。超过 30 天的数据由 compactor 后台删除，磁盘释放存在延迟。
+
+备选方案是运行文件级删除命令。该方案可能破坏 OpenObserve metadata 与数据文件一致性，因此禁止。
+
+## Risks / Trade-offs
+
+- [超过 30 天的数据不可恢复] → 部署说明明确这是观测数据策略，并在缩短期限前确认无需长期审计数据。
+- [compactor 清理不是即时发生] → 验证配置注入和容器健康，不以立即减少卷大小作为发布成功条件。
+- [`latest` 行为变化] → 保留既有镜像漂移审计和恢复点要求。
+- [stream-level retention 覆盖全局值] → 本 change 只定义全局默认；后续若引入 stream override，必须另行规范并审计。
+
+## Migration Plan
+
+1. 更新仓库 Compose、dotenv example、部署说明和配置测试。
+2. 在生产 dotenv 中设置 `ZO_COMPACT_DATA_RETENTION_DAYS=30`。
+3. 执行只读 `docker compose config` 预检，不输出环境值。
+4. 重建 OpenObserve service 并等待 healthcheck 通过。
+5. 回滚时恢复上一 retention 配置并重建服务；已经被 compactor 删除的数据不能通过配置回滚恢复。
+
+## Database Change Audit
+
+- PostgreSQL schema、Drizzle migration、seed、索引、约束和业务数据均不变。
+- 本 change 的 data retention 仅作用于 OpenObserve 的观测数据卷，不得运行 PostgreSQL migration 或数据清理命令。
+
+## Open Questions
+
+无。

openspec/changes/archive/2026-08-12-set-openobserve-retention-30-days/proposal.md

@@ -0,0 +1,42 @@
+## Why
+
+OpenObserve 当前依赖上游 3650 天默认保留期，应用 logs、metrics 和 traces 持续写入后会长期占用生产磁盘。生产单节点观测服务需要明确的 30 天全局保留边界，以限制存储增长并保持运维行为可预测。
+
+## What Changes
+
+- 为 OpenObserve Compose service 配置 `ZO_COMPACT_DATA_RETENTION_DAYS=30`。
+- 在生产 dotenv example 中记录同一安全默认值，并在部署说明中说明该值适用于 logs、metrics 和 traces，旧数据由 compactor 异步清理。
+- 增加部署配置测试，防止保留期退回 OpenObserve 上游默认值。
+
+## Capabilities
+
+### New Capabilities
+
+无。
+
+### Modified Capabilities
+
+- `openobserve-compose-service`: OpenObserve 生产服务必须将全局数据保留期显式限制为 30 天。
+
+## Impact
+
+- 受影响文件：`docs/deployment/docker-compose.yml`、`docs/deployment/env.production.example`、`docs/deployment/deployment.md` 和 telemetry deployment 配置测试。
+- 受影响系统：生产 OpenObserve compactor 及其本地持久化数据卷。
+- 高风险类别：数据保留与自动删除；配置生效后，超过 30 天的观测数据将进入异步清理流程。
+- 不涉及应用 API、PostgreSQL schema、业务数据或 Web UI。
+
+## Scope
+
+- 范围内：OpenObserve 全局观测数据保留期、Compose/env 示例、部署说明和配置验证。
+- 范围外：按 stream 设置不同保留期、历史数据导出、OpenObserve 版本固定、容量告警和对象存储迁移。
+
+## Non-goals
+
+- 不为 logs、metrics、traces 设置不同的 retention policy。
+- 不立即强制删除历史数据，也不修改 OpenObserve 数据卷内容。
+
+## Documentation Impact
+
+- 更新 `docs/deployment/deployment.md` 和部署示例，作为生产保留策略的权威说明。
+- `docs/arch/`、`docs/biz/`、根治理文件、app README 和生成的 Web API reference 不受影响。
+- 适用 Skill：`cnode-docs`，确保部署说明仅包含安全、可复用的配置值。

openspec/changes/archive/2026-08-12-set-openobserve-retention-30-days/specs/openobserve-compose-service/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: OpenObserve 观测数据必须默认保留 30 天
+
+生产 Compose SHALL 将 OpenObserve 的全局数据保留期显式配置为 30 天，使 logs、metrics 和 traces 中超过该期限的数据由 OpenObserve compactor 异步清理。部署 MUST NOT 通过直接删除 `openobserve-data` 文件实现 retention。
+
+#### Scenario: 渲染默认生产配置
+
+- **WHEN** 运维使用安全占位环境渲染 `docs/deployment/docker-compose.yml`
+- **THEN** `openobserve` service MUST 获得 `ZO_COMPACT_DATA_RETENTION_DAYS=30`
+- **AND** `docs/deployment/env.production.example` MUST 声明同一 30 天值
+
+#### Scenario: 30 天前数据进入清理流程
+
+- **WHEN** OpenObserve compactor 在 retention 配置生效后处理超过 30 天的观测数据
+- **THEN** 这些数据 MUST 由 OpenObserve 支持的 retention 机制异步清理
+- **AND** 部署流程 MUST NOT 假定重建容器后磁盘空间立即释放
+
+#### Scenario: 回滚 retention 配置
+
+- **WHEN** 运维恢复先前的 retention 值并重建 OpenObserve
+- **THEN** 新配置 MUST 只影响后续 compactor 行为
+- **AND** 运维 MUST NOT 声称配置回滚能够恢复已经删除的数据

openspec/changes/archive/2026-08-12-set-openobserve-retention-30-days/tasks.md

@@ -0,0 +1,11 @@
+## 1. MVP 配置
+
+- [x] 1.1 在生产 Compose 和 dotenv example 中将 OpenObserve 默认 retention 配置为 30 天
+- [x] 1.2 增加部署配置测试，验证 retention 变量和默认值
+
+## 2. 完整说明与验证
+
+- [x] 2.1 更新权威部署说明，记录全局适用范围、异步清理和不可恢复边界
+- [x] 2.2 运行 targeted test、secret scan、Compose 只读渲染和 OpenSpec strict validation
+- [x] 2.3 核对文档 owner、过期路径、安全示例和 PostgreSQL 无变更审计
+- [x] 2.4 在生产环境应用 30 天 retention，重建 OpenObserve 并验证健康状态

openspec/specs/openobserve-compose-service/spec.md

@@ -81,3 +81,25 @@ OpenObserve SHALL 将 `/data` 挂载到 Compose 声明的 `openobserve-data` vol
 - **WHEN** 运维准备拉取或重新创建 OpenObserve
 - **THEN** 运维 MUST 记录变更前后的实际 image ID 或 digest
 - **AND** 运维 MUST 在替换前确认上游版本兼容性和 `openobserve-data` 的可恢复备份
+
+### Requirement: OpenObserve 观测数据必须默认保留 30 天
+
+生产 Compose SHALL 将 OpenObserve 的全局数据保留期显式配置为 30 天，使 logs、metrics 和 traces 中超过该期限的数据由 OpenObserve compactor 异步清理。部署 MUST NOT 通过直接删除 `openobserve-data` 文件实现 retention。
+
+#### Scenario: 渲染默认生产配置
+
+- **WHEN** 运维使用安全占位环境渲染 `docs/deployment/docker-compose.yml`
+- **THEN** `openobserve` service MUST 获得 `ZO_COMPACT_DATA_RETENTION_DAYS=30`
+- **AND** `docs/deployment/env.production.example` MUST 声明同一 30 天值
+
+#### Scenario: 30 天前数据进入清理流程
+
+- **WHEN** OpenObserve compactor 在 retention 配置生效后处理超过 30 天的观测数据
+- **THEN** 这些数据 MUST 由 OpenObserve 支持的 retention 机制异步清理
+- **AND** 部署流程 MUST NOT 假定重建容器后磁盘空间立即释放
+
+#### Scenario: 回滚 retention 配置
+
+- **WHEN** 运维恢复先前的 retention 值并重建 OpenObserve
+- **THEN** 新配置 MUST 只影响后续 compactor 行为
+- **AND** 运维 MUST NOT 声称配置回滚能够恢复已经删除的数据