chore: improvements to clickhouse and data masking

[marcklingen]

Greptile Summary

This PR improves two self-hosting documentation pages: it adds a "Direct ClickHouse Access for Custom Tools" section to clickhouse.mdx, and refines data-masking.mdx with a new blob-storage timing warning, a corrected error-handling table (fail-open is the actual default, not fail-closed), and fixed container references (Worker vs Web) throughout the troubleshooting section.

• clickhouse.mdx: Adds guidance for users querying ClickHouse directly, clarifies the CLICKHOUSE_READ_ONLY_URL scope, and aligns the Cloud/BYOC recommendation paragraph with the updated description.
• data-masking.mdx: Fixes the inverted error-handling table (default is fail-open/false, not fail-closed), corrects "Langfuse Web container" → "Langfuse Worker container" in troubleshooting, adds a warning that events are written to blob storage before the masking callback runs, and clarifies that only invalid JSON (not structural schema mismatch) triggers error-handling behavior.

Confidence Score: 4/5

Safe to merge for the ClickHouse page; the data-masking page would benefit from one additional sentence clarifying blob-storage retention before operators rely on it for compliance decisions.

Both files are documentation-only changes. The ClickHouse additions are clear and accurate. The data-masking corrections (table column order, container name fixes) are genuine improvements. The one gap is that the new blob-storage warning in data-masking.mdx omits whether unmasked blob-storage data is ever cleaned up — this matters for operators reading this page to evaluate GDPR/HIPAA compliance posture, and a misleading silence there could lead to incorrect architectural decisions.

content/self-hosting/security/data-masking.mdx — the blob-storage data retention clause in the new warning callout (lines 55–61).

Security Review

• Unmasked data in blob storage: data-masking.mdx now discloses that events are written to blob storage before the masking callback runs, meaning blob storage retains unmasked PII. The documentation does not clarify whether this copy is ever replaced or deleted. Operators deploying server-side masking for GDPR/HIPAA/PCI DSS compliance may incorrectly assume their entire storage layer is protected.

Sequence Diagram

sequenceDiagram
    participant SDK as Langfuse SDK
    participant Web as Langfuse Web
    participant Bucket as Blob Storage (S3)
    participant Worker as Langfuse Worker
    participant Callback as Masking Callback
    participant CH as ClickHouse

    SDK->>Web: Send trace event (may contain PII)
    Web->>Bucket: Store UNMASKED event
    Note over Bucket: ⚠️ Unmasked data persists here
    Web->>Worker: Forward S3 reference (via Redis)
    Worker->>Bucket: Fetch unmasked event
    Worker->>Callback: POST OpenTelemetry object
    alt Callback succeeds
        Callback->>Worker: Return masked object
        Worker->>CH: Write MASKED data
    else Fail open (default)
        Worker->>CH: Write UNMASKED data, log warning
    else "Fail closed (FAIL_CLOSED=true)"
        Worker->>Worker: Drop event, log warning
    end

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
content/self-hosting/security/data-masking.mdx:55-61
**Blob storage data fate after masking is unspecified**

The new warning correctly flags that events land in blob storage *before* the masking callback runs, but it doesn't say whether that unmasked blob-storage copy is ever replaced or deleted after the Worker processes the masked version. Looking at the sequence diagram (SDK → Web → S3 (unmasked) → Worker → Callback → ClickHouse), there is no "update S3" or "delete from S3" step. If unmasked data persists in blob storage indefinitely, users deploying this feature for GDPR, HIPAA, or PCI DSS compliance may believe their storage layer is protected when only ClickHouse and downstream views receive masked data. A single sentence clarifying the blob-storage retention behavior (e.g., whether it is retained as-is, or whether client-side masking is required to prevent PII reaching blob storage at all) would prevent a compliance blind-spot for operators who read this warning and draw the wrong conclusion.

_{Reviews (1): Last reviewed commit: "improvements to clickhouse and data mask..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	Jun 6, 2026 8:29am

[github-actions]

@claude review