Back to releases
v0.8.0

Reliability and operability (v0.8.0)

Failure retry, Generation rebuild, OpenTelemetry observability, and asynq task governance ship — giving Langhuan the long-term runnability and recoverability needed to enter release readiness.

ReliabilityObservabilityOperations

After v0.7.x connected the main knowledge-processing and retrieval pipeline, v0.8.0 focuses on a different goal: making this service run long-term, and giving you the means to locate and recover from failures. This release doesn’t add user-facing product features — it fills in retry, rebuild, observability, and resource protection, preparing Langhuan for v1.0.0 release readiness.

Failures can be safely retried

Any step of the ingest pipeline (parse, chunk, embedding, index, publish) can fail, and previously a failure meant rebuilding the knowledge base. There are now three retry entry points:

  • Document-level retry: POST /api/v1/.../documents/:id/retry — resumes from the failed revision.
  • Job-level retry: POST /api/v1/.../jobs/:id/retry — targets a single asynq task.
  • MCP retry: a new document_retry tool, so MCP clients can trigger it too.

Under Session auth, retry requires admin/owner; an API key uses ScopeDocumentsWrite. The retry chain carries one critical contract: the parse job payload must include the current active index_generation_id, so that a retry after a reindex lands on the correct Generation. On enqueue failure, a FailReset compensation marks the revision/job back to failed — no half-finished state is left behind.

Generation rebuild

Switching a knowledge base’s model or changing its chunking config requires rebuilding the index. v0.8.0 wires Generation reindex into the double-buffered mechanism: a new Generation builds in staging, atomically activates, and the old Generation retires into a recovery window, while the active Generation stays queryable throughout. Duplicate requests and worker restarts never break the index currently serving traffic.

OpenTelemetry observability

This is the heaviest part of v0.8.0. The metrics foundation fully migrates to the OpenTelemetry SDK:

  • The /metrics endpoint is retained for Prometheus scraping compatibility; the OTLP exporter is off by default and only pushes when you configure an endpoint.
  • Metric names follow a fixed contract (e.g. langhuan_http_requests_total); counters never set WithUnit("1") (the exporter would otherwise mangle them into a _ratio_total suffix), and Prometheus legacy name validation is enabled to avoid emitting illegal dotted names.
  • RAG retrieval spans follow gen_ai semantic conventions (gen_ai.operation.name=retrieval/embeddings, gen_ai.data_source.id, rag.retrieval.empty_result).
  • The raw query is never written to a span — neither as an attribute nor as an event — consistent with the log-redaction policy.
  • Traces are on by default, with a configurable sample rate (observability.traces.sample_rate).

With per-stage timing (upload / parse / chunk / embedding / index / publish) and key counters, you can locate slow ingest, parse failures, embedding failures, indexing failures, and publish failures down to the specific stage, correlated to workspace / document / revision / job / generation.

asynq task governance

The task queue graduates from “runs” to “controllable”:

  • MaxRetry, Timeout, and Retention are all configurable — no more hardcoded values.
  • An Inspector and /admin/queues/* dead-letter management endpoints show backlogged, in-retry, and terminated tasks.
  • Dead-letter inspection policy is explicit, so a terminated-failure task won’t retry indefinitely and hold a worker.

Resource protection and cleanup

  • Chunk count, embedding concurrency, and batch size all have configurable caps — large files, zip bombs, and abnormal images can’t hold worker resources indefinitely.
  • failed / staging / retired projections get controlled scheduled cleanup, preserving the active Generation and the fact-layer data within the recovery window.
  • A backup-and-restore runbook is complete: on an empty database and empty object storage, you can repeatedly walk through install → backup → restore → single-binary smoke.

With this release, Langhuan has the recoverability to run long-term internally. The remaining known tech debt (otelaws instrumentation for S3 object storage, the Web Console queue-monitoring front-end page) is recorded in docs/KNOWN_BUGS.md and doesn’t affect the current main pipeline.