docs: japan cloud

[clemra]

No description provided.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	Apr 24, 2026 11:18am

[github-actions]

@claude review

[claude]

LGTM — straightforward documentation update adding the Japan (beta) region to the data regions table and subprocessors list.

Extended reasoning...

Overview

This PR adds documentation for the new Japan (beta) cloud region across two security documentation files: content/security/data-regions.mdx and content/security/subprocessors.mdx. Changes include adding the Japan region row to the regions table, a URL example, updating the introductory text, and a new subprocessors section mirroring the EU region structure with AWS/Clickhouse hosted in Japan.

Security Risks

No security risks. These are purely documentation changes with no code logic, authentication, or data-handling changes.

Level of Scrutiny

Low scrutiny required. The changes follow the exact same pattern used for the existing US, EU, and HIPAA regions. The subprocessor table for Japan correctly shows AWS and Clickhouse in Japan and the remaining processors in EU, consistent with the explanatory text.

Other Factors

No bugs were found. The Vercel preview deployed successfully. The changes are internally consistent and follow established documentation conventions.

[claude]

Straightforward docs + region-selector config addition for the new Japan cloud region; the only finding is a minor labeling-consistency nit already posted inline.

Extended reasoning...

Overview

This PR adds the new Japan cloud region (jp.cloud.langfuse.com, AWS ap-northeast-1/Tokyo) to four places: the cloudRegions map and selector order in lib/cloud-regions.ts, the region card config in app/cloud/[[...path]]/page.tsx, a new row + bullet in content/security/data-regions.mdx, and a new 'Langfuse Cloud: Japan' subprocessors section + an intro-sentence tweak in content/security/subprocessors.mdx. All changes follow the existing patterns established for the US/EU/HIPAA regions.

Security risks

None meaningful. The code change is a new entry in a static region-config map and a new card in a client-side selector; the URL is a fixed https endpoint with no user-controlled interpolation, and the existing buildCloudRedirectUrl/stripControlChars logic handles it the same way it handles the other regions. The MDX changes are pure content. Subprocessors disclosures are compliance-relevant but this is a documentation addition, not a policy change.

Level of scrutiny

Low. This is a docs-and-config PR that mirrors existing patterns exactly — no logic changes, no new abstractions, no auth/crypto touchpoints, and no CODEOWNER-sensitive code. Mechanical additions to parallel structures.

Other factors

The bug hunter flagged a real but minor inconsistency: cloudRegions.jp.label and the MDX bullet list say 'Japan (beta)', but the /cloud selector card, the data-regions table row, and the subprocessors heading all say plain 'Japan'. That's worth the author picking one form — but it's a labeling nit, not a correctness issue, and the inline comment already surfaces the specific locations. No other issues found.

[claude]

🟡 The new Japan region is labeled inconsistently across surfaces: lib/cloud-regions.ts uses "Japan region (beta)" (rendered in the ToAppButton dropdown) and the bullet list in data-regions.mdx says "Japan (beta)", but the /cloud region selector card (app/cloud/[[...path]]/page.tsx), the regions table row in data-regions.mdx, and the subprocessors.mdx heading all render as plain "Japan". Even within data-regions.mdx the same region appears both with and without "(beta)". Standardize on one form across all five surfaces.

Extended reasoning...

What the bug is

This PR adds the new Japan region to five user-visible surfaces, but three of them label it as generally available while two call it beta:

#	Surface	Label	Beta?
1	lib/cloud-regions.ts:11 (cloudRegions.jp.label)	Japan region (beta)	yes
2	app/cloud/[[...path]]/page.tsx:52 (regionCards.jp.title)	Japan	no
3	content/security/data-regions.mdx:20 (regions table)	**Japan**	no
4	content/security/data-regions.mdx:36 (bullet list)	Japan (beta):	yes
5	content/security/subprocessors.mdx:42 (section heading)	## Langfuse Cloud: Japan	no

How it manifests / code path

The label from (1) is not dead code — cloudRegions[key].label is rendered at components/ToAppButton.tsx:92 inside the multi-region dropdown menu (<Link href={region.url}>{region.label}</Link>). So a signed-in user who opens the region picker from the ToAppButton will see Japan region (beta), then click through to the /cloud page (or the docs) and see plain Japan with no beta indicator. Within the same data-regions.mdx page, the regions table at line 20 shows Japan while the bullet list 16 lines below at line 36 shows Japan (beta) — an internal contradiction on one page.

Why existing code does not prevent it

The five surfaces are independent: the region selector card titles live in a local regionCards map in page.tsx, the MDX docs hard-code the text, and the subprocessors heading is a free-form ## Langfuse Cloud: Japan. None of them derive from cloudRegions.jp.label, so there is no single source of truth forcing them to agree.

Impact

Users get conflicting signals about whether the Japan region is production-ready. Readers reviewing the docs before sending data to a new region (a compliance/security decision) are particularly sensitive to the GA-vs-beta distinction. The concrete proof below shows a single user journey that crosses the inconsistency:

Step-by-step proof

1. Signed-in user on cloud.langfuse.com opens the ToAppButton → the dropdown renders cloudRegions.jp.label = "Japan region (beta)" (via components/ToAppButton.tsx:92).
2. Same user navigates to /cloud to pick a region → the selector card renders regionCards.jp.title = "Japan" (no beta).
3. User clicks Data Regions in the docs (/security/data-regions) → the regions table row shows Japan (no beta) at line 20, then six lines later the bullet list at line 36 shows "Japan (beta)". Same page, two different statuses.
4. User opens Subprocessors (/security/subprocessors) → the section heading at line 42 is "## Langfuse Cloud: Japan" (no beta).

Result: four of the five touchpoints the user sees disagree with the canonical label.

How to fix

Pick one form and apply it everywhere. If the region really is beta (as cloudRegions.jp.label says):

• app/cloud/[[...path]]/page.tsx:52: title: "Japan (beta)"
• content/security/data-regions.mdx:20: | **Japan (beta)** | ...
• content/security/subprocessors.mdx:42: ## Langfuse Cloud: Japan (beta)

If it is GA, drop (beta) from lib/cloud-regions.ts:11 and data-regions.mdx:36 instead. Either way, the table row and the bullet list within data-regions.mdx should match each other.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[claude]

🔴 🔴 Two notebook cells add the new # Other Langfuse data regions include … comment as a source-array entry without a trailing \n, while the line it replaces had one. Jupyter concatenates source entries verbatim, so the new string fuses onto whatever comes next: in cookbook/otel_integration_mlflow.ipynb (cell 3, line 8) it swallows the os.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] = … assignment, silently commenting out the Authorization header so OTLP ingestion runs unauthenticated and 401/403s against Langfuse; in cookbook/integration_librechat.ipynb (cell 2, ~line 50) it swallows the closing `````` bash fence, so the fence no longer starts a line and the subsequent > **Note** blockquote renders inside the unclosed code block. Fix: append `\n` to the new comment string in both `.ipynb` files (the corresponding `.md`/`.mdx` files already have the newline and are fine).

Extended reasoning...

What the bug is

Jupyter stores a cell's source as a JSON array of strings that are concatenated verbatim when the notebook is executed or rendered — there is no implicit newline between array entries. Each line therefore has to end with \n except the last. This PR introduces two new cell-source entries that drop the trailing \n, so they fuse onto the next array entry.

Instance 1 — cookbook/otel_integration_mlflow.ipynb (functional breakage)

Cell 3 (code cell) source entries 7–9 are now:

[7] 'os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = "https://cloud.langfuse.com/api/public/otel/v1/traces"  # 🇪🇺 EU data region\n'
[8] '# Other Langfuse data regions include 🇺🇸 US: …, 🇯🇵 Japan: …, ⚕️ HIPAA: https://hipaa.cloud.langfuse.com/api/public/otel'   ← no trailing \n
[9] 'os.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"\n'

I verified this by loading the notebook as JSON with json.load and dumping repr() of entries 7/8/9 — entry 8 ends at …hipaa.cloud.langfuse.com/api/public/otel with no \n, entry 9 starts with os.environ[…HEADERS….

Step-by-step proof (instance 1)

1. Jupyter executes ''.join(cell['source']) to build the cell code.
2. The join of entries 8 and 9 produces a single physical line:
   # Other Langfuse data regions include … hipaa.cloud.langfuse.com/api/public/otelos.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
3. Because that line starts with #, Python treats it all as a comment. os.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] is never set.
4. Later in the cell, OTLPSpanExporter() (and mlflow's autolog) reads OTEL_EXPORTER_OTLP_TRACES_HEADERS from the environment. With the variable unset, the exporter sends OTLP traces without an Authorization header.
5. Langfuse's OTLP ingestion endpoint requires Basic Auth, so every exported span is rejected with 401/403 — the cookbook silently stops producing traces in Langfuse.

The sibling content/guides/cookbook/otel_integration_mlflow.md in this same PR does include the trailing newline on the new comment line, confirming this is specifically a notebook-write bug, not an upstream content issue.

Instance 2 — cookbook/integration_librechat.ipynb (rendering breakage)

Cell 2 (markdown cell) has consecutive source entries:

'# Other Langfuse data regions include 🇺🇸 US: …, 🇯🇵 Japan: …, ⚕️ HIPAA: https://hipaa.cloud.langfuse.com'   ← no trailing \n
'```\n'

After concatenation the rendered markdown contains the literal line …hipaa.cloud.langfuse.com```` — the closing triple-backtick is glued to the end of the comment. Per CommonMark/GFM, a closing code fence must appear on a line by itself (optionally indented); a fence prefixed by text does not close the block. The result is that the ```bash fence opened earlier in the cell never closes, and the subsequent > Note: …` admonition (plus everything after it in the cell) renders inside the bash code block instead of as a blockquote.

Why existing code doesn't prevent this

Notebooks are checked in as raw JSON and the PR touches ~230 files, so the missing \n slipped through review. There is no linter or CI check in this repo that validates notebook source arrays end each non-final entry with \n.

Fix

In both .ipynb files, append \n to the new comment string:

• cookbook/otel_integration_mlflow.ipynb cell 3, entry 8 → '…hipaa.cloud.langfuse.com/api/public/otel\n'
• cookbook/integration_librechat.ipynb cell 2, the new comment → '…hipaa.cloud.langfuse.com\n'

One-character change per file. The corresponding .md/.mdx siblings are already correct and can be used as the reference.

[claude]

🔴 The commented alternate-region URLs on line 156 drop the /v1/traces suffix that the active line just above uses — but this is the signal-specific OTEL_EXPORTER_OTLP_TRACES_ENDPOINT variable, which per OTLP spec is used verbatim (no auto-append). A user who swaps the EU URL for the JP/US/HIPAA URL from the comment will point at the OTLP root and their traces will 404 or misroute. Same regression appears in content/guides/cookbook/otel_integration_mlflow.md line 36 and cookbook/otel_integration_mlflow.ipynb. Fix: append /v1/traces to each of the three URLs in these three sites.

Extended reasoning...

What the bug is

In content/integrations/native/opentelemetry.mdx the active line at 155 sets the signal-specific variable OTEL_EXPORTER_OTLP_TRACES_ENDPOINT to https://cloud.langfuse.com/api/public/otel/v1/traces (with the /v1/traces suffix). The new comment at line 156 lists alternate regions as .../api/public/otel (no suffix). This directly contradicts the Callout sentence at line 152 immediately above, which states: "If your collector requires signal-specific environment variables, the trace endpoint is /api/public/otel/v1/traces."

Why this actually breaks things (OTLP behaviour)

Per the OTLP spec, the two env vars behave differently:

• OTEL_EXPORTER_OTLP_ENDPOINT (non-signal-specific) — the SDK appends v1/traces, v1/metrics, v1/logs automatically.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT (signal-specific) — the SDK uses the URL verbatim. No suffix is appended.

So when a user copy-pastes https://jp.cloud.langfuse.com/api/public/otel from the new comment into OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, the exporter will POST to that URL directly, not to …/otel/v1/traces. Langfuse's OTLP ingestion path expects the signal suffix, so the request 404s (or, on exporters that silently succeed on a non-2xx, spans are lost).

Step-by-step proof

1. User reads the Callout at opentelemetry.mdx:152 saying the trace endpoint for signal-specific vars is /api/public/otel/v1/traces.
2. User sees the active line at :155 correctly using https://cloud.langfuse.com/api/public/otel/v1/traces.
3. User wants the JP region, so copies https://jp.cloud.langfuse.com/api/public/otel from the comment at :156 and sets:
   OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://jp.cloud.langfuse.com/api/public/otel".
4. OTel SDK sends the POST to exactly that URL (spec: signal-specific is used as-is).
5. Langfuse's ingest is at …/api/public/otel/v1/traces, not …/api/public/otel; the request does not land on the trace ingest handler.
6. Spans are silently dropped or rejected, depending on exporter.

The pre-PR line had # OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://us.cloud.langfuse.com/api/public/otel/v1/traces" — with the suffix — so this is a regression introduced by this PR.

Why sibling edits in this PR are fine

The global-replace of # OTEL_EXPORTER_OTLP_ENDPOINT=…/api/public/otel in pipecat.mdx and the top block of opentelemetry.mdx (line 129) is correct, because those sites use the non-signal-specific OTEL_EXPORTER_OTLP_ENDPOINT, which does auto-append v1/traces. The bug only affects the three signal-specific sites listed below.

How to fix

Append /v1/traces to each URL in the replacement comment at three sites:

• content/integrations/native/opentelemetry.mdx:156
• content/guides/cookbook/otel_integration_mlflow.md:36
• cookbook/otel_integration_mlflow.ipynb (the corresponding cell source entry)

E.g.# Other Langfuse data regions include 🇺🇸 US: https://us.cloud.langfuse.com/api/public/otel/v1/traces, 🇯🇵 Japan: https://jp.cloud.langfuse.com/api/public/otel/v1/traces and ⚕️ HIPAA: https://hipaa.cloud.langfuse.com/api/public/otel/v1/traces.

[claude]

🔴 The new Data region row contradicts the HIPAA compliance row in the same file: the Data region row at line 147 lists HIPAA only under the Enterprise column, but the HIPAA compliance row at line 166 marks Pro='Yes' and Enterprise='Yes', and content/security/hipaa.mdx explicitly tells users to "Upgrade to Pro plan or higher" to use HIPAA. A Pro prospect reading this pricing matrix will conclude the HIPAA data region is Enterprise-only while the HIPAA setup guide tells them Pro is enough — the pre-PR "US or EU" row sidestepped this by not mentioning HIPAA at all. Likely fix: add HIPAA to the Pro column (e.g. US, EU, Japan, or HIPAA).

Extended reasoning...

What the bug is

On md-override/pricing.md:147 the PR rewrites the Data region row as:

| [Data region] | US, EU, or Japan | US, EU, or Japan | US, EU, or Japan | US, EU, Japan, or HIPAA |

HIPAA is only listed in the Enterprise column. But 19 lines below, on md-override/pricing.md:166, the Compliance section says:

| [HIPAA compliance](/security/hipaa) | -- | -- | Yes | Yes |

i.e. HIPAA compliance is available starting from the Pro tier. And content/security/hipaa.mdx reinforces that Pro is the entry point:

• line 16: "Upgrade to Pro plan or higher" (step 4 of the HIPAA setup guide)
• the BAA eligibility notice lists "Pro, Teams, or Enterprise plan" as HIPAA-eligible

Why this is a real contradiction

Langfuse's HIPAA model ties compliance to the region: the only place a BAA automatically applies is hipaa.cloud.langfuse.com (per hipaa.mdx line 34). So "HIPAA compliance = Yes on Pro" only makes sense if a Pro customer can actually use the HIPAA data region. The new Data region row says they cannot — only Enterprise can select HIPAA.

Step-by-step proof of the user-visible contradiction

1. A healthcare-adjacent Pro prospect lands on /pricing and scans the matrix.
2. In the Security section (line 147) they see Pro: "US, EU, or Japan" — no HIPAA.
3. Sixteen rows later (line 166) they see HIPAA compliance: Yes on Pro — implying HIPAA is included.
4. They click through to /security/hipaa. Step 4 reads "Upgrade to Pro plan or higher", and the eligibility notice confirms Pro is HIPAA-eligible.
5. They now have two authoritative Langfuse surfaces telling them Pro grants HIPAA access, and one (the Data region row they just saw on the same pricing page) telling them HIPAA is Enterprise-only. The purchase/compliance decision is blocked on a contradiction.

Why this is new (not pre-existing)

The pre-PR row was US or EU | US or EU | US or EU | US or EU — it didn't mention HIPAA at all, so the HIPAA compliance row carried the eligibility story alone without conflict. The PR's expansion to enumerate regions per tier exposed and codified the inconsistency.

Fix

Most likely the Pro column should read US, EU, Japan, or HIPAA (matching the Core/Pro "Yes" in the HIPAA compliance row). Alternatively, if the intent was to restrict the HIPAA data region to Enterprise, the HIPAA compliance row and hipaa.mdx step 4 need to be tightened to Enterprise-only — but that would be a more invasive change that also contradicts the existing HIPAA signup flow.

[claude]

🔴 The DPA's §10 (International Transfers) at lines 117-125 has per-instance paragraphs describing hosting location and transfer mechanism for EU Cloud, US Cloud, and HIPAA Cloud, but no clause for Japan Cloud — even though this PR adds Japan Cloud to §1 Applicability Notice (line 18) and §2 Definitions (line 49). A Japan Cloud client reviewing the DPA will find their instance advertised in §1/§2 but undocumented in §10, which is material because Japan's transfer analysis differs (EU adequacy decision 2019/419 applies for EEA→JP, so SCCs are not required — unlike the US/HIPAA clauses). Add a per-instance paragraph in §10 along the lines of: "Data processed in the Japan Cloud is hosted in Japan (AWS ap-northeast-1). Transfers from the EEA/UK/Switzerland rely on the EU Commission adequacy decision for Japan (Decision 2019/419) where applicable; otherwise the EU SCCs (Module 2 and/or 3) apply."

Extended reasoning...

What the bug is

This PR adds "Japan Cloud" to two places in content/security/dpa.mdx:

• §1 Applicability Notice (line 18): the DPA is now advertised as "available for any Client of the Langfuse Cloud platform (… Japan Cloud at https://jp.cloud.langfuse.com, …)".
• §2 Definitions (line 49): the term 'EU Cloud' / 'US Cloud' / 'Japan Cloud' / 'HIPAA Cloud' is defined.

But §10 International Transfers (lines 117–125) was not updated. §10 follows a per-instance pattern: after an opening general clause at line 119, it devotes one paragraph each to EU Cloud (line 121), US Cloud (line 123), and HIPAA Cloud (line 125), stating where the data is physically hosted and which transfer mechanism Langfuse relies on. After this PR, Japan Cloud is listed as a supported instance in §1/§2 but has no matching paragraph in §10.

Why the general clause does not cover it

The general paragraph at line 119 is a catch-all ("Langfuse will implement an appropriate transfer mechanism for each transfer …"). It does not tell a Japan Cloud customer (a) where their data is physically hosted, or (b) which specific mechanism applies for transfers into Japan. This matters because Japan's transfer-mechanism analysis is materially different from the US/HIPAA clouds: Japan benefits from EU Commission adequacy decision 2019/419, which means EEA→JP transfers do not require SCCs — in contrast to the US/HIPAA paragraphs that explicitly rely on SCCs and the EU–US Data Privacy Framework. Japan Cloud therefore cannot be covered "by inference" from the US/HIPAA paragraphs; they describe a different legal basis.

Why this is new (not pre-existing)

The §10 clauses for EU/US/HIPAA existed before this PR. The pre-existing DPA did not list Japan Cloud anywhere, so there was no inconsistency. This PR is the change that introduces Japan Cloud as a covered instance (§1, §2), which creates the new gap in §10. The omission is introduced by this PR's partial update to the same file.

Step-by-step proof

1. A prospective Japan Cloud customer opens /security/dpa for their legal review.
2. At §1 Applicability Notice (line 18) they read that this DPA is "available for" clients of Japan Cloud at https://jp.cloud.langfuse.com.
3. At §2 Definitions (line 49) they see 'EU Cloud' / 'US Cloud' / 'Japan Cloud' / 'HIPAA Cloud' defined as one of the instances the DPA covers.
4. They jump to §10 International Transfers (lines 117–125) to verify hosting location and the transfer mechanism Langfuse will rely on for their data.
5. They find per-instance paragraphs for EU Cloud ("remains within the EEA…"), US Cloud ("primarily hosted in the United States; Langfuse relies on the EU Standard Contractual Clauses…"), and HIPAA Cloud ("hosted in a dedicated, HIPAA-compliant environment in the United States…").
6. There is no paragraph for Japan Cloud. The customer cannot confirm (a) where their data is hosted, (b) that EEA→JP transfers rely on the Japan adequacy decision 2019/419, or (c) what applies where adequacy does not.
7. Their compliance review is blocked on text the DPA promised would be there.

Fix

Add a per-instance paragraph to §10 mirroring the style of the existing EU/US/HIPAA clauses, for example:

Data processed in the Japan Cloud is hosted in Japan (AWS ap-northeast-1). Transfers from the EEA/UK/Switzerland to Japan rely on the EU Commission's adequacy decision for Japan (Decision 2019/419) where applicable; in other cases the EU Standard Contractual Clauses (Module 2 and/or 3) apply.

This keeps §10 consistent with §1/§2 and gives Japan Cloud customers the same legal clarity the other instances already have.

[claude]

🟡 The PR adds Japan as a peer cloud region in data-regions.mdx, dpa.mdx, subprocessors.mdx, hipaa.mdx and pricing.md, but four other public-facing pages in the diff's neighborhood still enumerate only "US, EU, HIPAA" and now contradict the new region list: content/security/index.mdx:70, content/security/security-faq.mdx:36, content/handbook/chapters/why.mdx:92, and content/handbook/product-engineering/architecture.mdx:101. Nit/docs-only: update these four enumerations to include Japan (matching the form already used in hipaa.mdx:13 — "EU, US, and Japan data regions") so the /security section stays self-consistent.

Extended reasoning...

What the bug is

This PR introduces Japan as a peer cloud region across multiple public-facing surfaces, including the canonical content/security/data-regions.mdx table (line 20) and bullet list (line 36), the DPA at content/security/dpa.mdx (lines 18, 49), content/security/subprocessors.mdx (new ## Langfuse Cloud: Japan section at line 42), content/security/hipaa.mdx:13 (updated to "EU, US, and Japan data regions"), and md-override/pricing.md:147. However, four other public-facing pages that enumerate the supported cloud regions were not updated and still advertise only "US, EU, HIPAA":

#	File:Line	Current text
1	content/security/index.mdx:70	"Langfuse Cloud – fully‑managed SaaS (multi‑tenant) with US, EU and HIPAA data regions"
2	content/security/security-faq.mdx:36	"Yes. EU, US and HIPAA‑ready US zones are available, and self‑hosted deployments let you choose any region and infrastructure."
3	content/handbook/chapters/why.mdx:92	"Data Regions: Choose between US, EU, or HIPAA-ready data regions on Langfuse Cloud—or self-host anywhere."
4	content/handbook/product-engineering/architecture.mdx:101	mermaid subgraph label Langfuse Cloud (US, EU, HIPAA)

I confirmed all four by grepping the current tree — none of these four files are in the PR diff.

Why this is newly introduced by this PR

Before this PR the three-region enumeration ("US, EU, HIPAA") was factually correct because Japan did not exist as a region. The PR adds Japan to data-regions.mdx, dpa.mdx, subprocessors.mdx, hipaa.mdx and pricing.md, but misses these four enumeration sites. That turns what was previously a consistent three-region story into a contradiction inside the /security section of the docs.

Step-by-step proof of the user-visible inconsistency

1. A Japan-based prospect lands on /security (the Security Center landing page). Line 70 states Langfuse Cloud runs in "US, EU and HIPAA data regions" — Japan absent.
2. The same prospect navigates to /security/security-faq to check region availability. Line 36 says "EU, US and HIPAA‑ready US zones are available" — Japan absent.
3. They finally click through to /security/data-regions (the target of the links on both pages), whose new table at line 20 now includes a "Japan" row pointing at jp.cloud.langfuse.com. The same page at line 36 also advertises "Japan (beta)" in the bullet list.
4. They now have three Langfuse-authoritative surfaces disagreeing about whether Japan is a supported region — two say it is not, one says it is. A procurement reviewer reading /security first may disqualify Langfuse before ever reaching /security/data-regions.
5. The /handbook pages replay the same contradiction at smaller reach.

How to fix

In all four files, update the three-region enumeration to include Japan, matching the form already adopted elsewhere in this PR (content/security/hipaa.mdx:13 was updated to "EU, US, and Japan data regions"):

• content/security/index.mdx:70: "US, EU, Japan, and HIPAA data regions"
• content/security/security-faq.mdx:36: "EU, US, Japan, and HIPAA‑ready US zones are available"
• content/handbook/chapters/why.mdx:92: "Choose between US, EU, Japan, or HIPAA-ready data regions on Langfuse Cloud"
• content/handbook/product-engineering/architecture.mdx:101: mermaid label Langfuse Cloud (US, EU, JP, HIPAA)

Severity

Nit / documentation-only. The Japan region genuinely exists and can be used; there is no functional breakage. But the omission lives on the most visible /security pages read during procurement/compliance review, so it is worth a one-line fix per file rather than leaving the /security section internally inconsistent.

[claude]

🟡 The JP migration guide labels the SOURCE host default as (Example: US Cloud), but that URL is the EU region — the US URL is . The DEST host on the next line is correctly paired ( with ), so the SRC mismatch is clearly unintentional. Fix: change the comment to (or swap the URL to ). Same mismatch exists in the paired cell 3.

Extended reasoning...

What the bug is

On content/guides/cookbook/example_data_migration-jp.mdx:42, the PR introduces:

os.environ["LANGFUSE_SOURCE_HOST"] = "https://cloud.langfuse.com"  # 例: US クラウド

The URL https://cloud.langfuse.com is the EU region — lib/cloud-regions.ts:2-3 defines cloud.langfuse.com as the EU region, and content/security/data-regions.mdx:19-20 confirms EU = cloud.langfuse.com while US = us.cloud.langfuse.com. The inline comment # 例: US クラウド (literally "Example: US Cloud") therefore contradicts what the URL actually points at. The same mismatch exists in the paired notebook cookbook/example_data_migration-jp.ipynb (cell 3, which the .mdx is generated from).

Why the mismatch is clearly unintentional (not a placeholder convention)

The very next line in the same snippet is correctly paired:

os.environ["LANGFUSE_DEST_HOST"] = "https://jp.cloud.langfuse.com"  # 例: JP クラウド

jp.cloud.langfuse.com correctly matches 例: JP クラウド. Also, the notebook header at line 12 explicitly lists the four distinct regions ("US ↔ EU ↔ JP ↔ HIPAA"), so the author clearly knows US and EU are different regions. The SRC line is just a straight label/URL bug.

Step-by-step proof of the user-visible impact

1. A Japanese user lands on the new JP migration cookbook at /guides/cookbook/example_data_migration-jp (the guide is explicitly aimed at Japanese users migrating to JP Cloud).
2. They skim the setup block at line 42, see the comment # 例: US クラウド, and — trusting the comment — leave the default URL in place thinking "good, the example is showing me the US URL".
3. They run the migration with their US project's pk-lf-… / sk-lf-… credentials.
4. Those credentials fail auth_check() on cloud.langfuse.com (EU), because US-region keys are not valid on the EU instance (regions are fully separated — content/security/data-regions.mdx:15 notes that "all data, user accounts, and infrastructure are completely separated"). The migration aborts with an auth failure, and the user is left confused about why their US keys don't work against what the comment told them was the US cloud.

(If, instead, the user happened to have EU credentials lying around and tried those, the script would silently read from the wrong source project — an even worse failure mode because the migration could appear to succeed while pulling data from the EU instance.)

How to fix

One-character-class change in two places. Either:

• Change the comment to match the URL: # 例: EU クラウド — consistent with the adjacent # 例: JP クラウド pattern and keeps the cloud.langfuse.com default.
• Or change the URL to match the comment: "https://us.cloud.langfuse.com" # 例: US クラウド — also fine.

Apply the same fix to the corresponding cell in cookbook/example_data_migration-jp.ipynb (the .mdx is generated from it).

Note on scope

One verifier observed that the English sibling content/guides/cookbook/example_data_migration.mdx:45 has the identical # e.g. US cloud typo on the EU URL, so this bug was copied from the existing English file into the new JP translation rather than being newly invented. However, since the PR creates the JP file, the fix is well-scoped to this PR (and ideally the English sibling should be fixed too, though that is out of scope here).

[claude]

🟡 The PR's replace-all of the US alternate-URL line left stale scaffolding in 3 files that sibling files cleaned up cleanly: content/integrations/agentic-data-stack.mdx:54 and content/integrations/other/librechat.mdx:40 still have orphan # US region / # 🇺🇸 US Data Region header lines sitting above the new all-regions comment that enumerates US/Japan/HIPAA; and content/guides/cookbook/integration_weco.mdx:63 still has the stale #os.environ[...] # 🇪🇺 EU region fallback line below the new comment. Purely cosmetic (no functional breakage), but the integration_weco.mdx case also means the published cookbook page renders different example code from the paired .ipynb and the sibling content/integrations/other/weco.mdx, both of which were cleaned up correctly in the same PR. Fix: delete the orphan header in the two mdx files and the stale EU fallback line in the weco cookbook.

Extended reasoning...

What the bug is

This PR performed a mostly-global replacement that swapped the old # os.environ["LANGFUSE_BASE_URL"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region alternate-region line (and its shell / env-file variants) for a new comprehensive comment enumerating US, Japan, and HIPAA. In three files the replacement was incomplete and left adjacent lines that no longer make sense:

1. content/integrations/agentic-data-stack.mdx:54-55 — the standalone header # US region now labels a line that lists all four regions (US/Japan/HIPAA + the EU line directly above):

   # US region
   # Other Langfuse data regions include 🇺🇸 US: ..., 🇯🇵 Japan: ... and ⚕️ HIPAA: ...
   

2. content/integrations/other/librechat.mdx:40-41 — same pattern with # 🇺🇸 US Data Region as the stale header above the catch-all comment.

3. content/guides/cookbook/integration_weco.mdx:61-63 — here the PR added the new all-regions comment on line 62 but did not remove the pre-existing stale EU fallback on line 63:

   os.environ["LANGFUSE_BASE_URL"] = "https://us.cloud.langfuse.com"  # 🇺🇸 US region
   # Other Langfuse data regions: 🇪🇺 EU https://cloud.langfuse.com, 🇯🇵 Japan ..., ⚕️ HIPAA ...
   #os.environ["LANGFUSE_BASE_URL"] = "https://cloud.langfuse.com"  # 🇪🇺 EU region   ← stale, redundant

Why these are real regressions introduced by this PR

The PR's sibling files in the exact same edit set show what the intended cleanup was:

• content/integrations/gateways/openrouter.mdx:51-53 and content/integrations/gateways/vercel-ai-gateway.mdx:31-33 both correctly removed the stale # 🇺🇸 US region header along with the commented BASE_URL line, leaving only the new all-regions comment.
• content/integrations/other/weco.mdx:61-62 and cookbook/integration_weco.ipynb both replaced the EU fallback line with the new comment (diff shows a - on the old EU line plus a + on the new comment), rather than merely appending.

So the three files above simply missed the cleanup. This is strictly new inconsistency — before the PR there was no catch-all comment, so no orphan header / fallback issue existed.

Impact

Functionally harmless: every affected line is inside a code-block comment, so nothing is executed. The user-visible effect is:

• In the two .mdx integration docs, a "US region" label now sits above a sentence that describes all three non-EU regions — mildly confusing to readers copy-pasting the example.
• In integration_weco.mdx, the cookbook page that ships to /guides/cookbook/integration_weco renders a redundant EU fallback directly under a comment that already mentions EU, and the rendered example diverges from the paired .ipynb and the sibling content/integrations/other/weco.mdx page in the same PR.

Step-by-step proof (weco cookbook divergence)

1. Open cookbook/integration_weco.ipynb in Jupyter (or view its diff in this PR). The cell contains exactly two region lines: the active US assignment, then the new all-regions comment. The EU fallback line is gone (the diff shows a - for #os.environ[...] # 🇪🇺 EU region).
2. Open content/integrations/other/weco.mdx at lines 61-62. Same two-line state: active US assignment + new comment, no EU fallback. The diff shows the PR replaced the EU fallback line.
3. Open content/guides/cookbook/integration_weco.mdx at lines 61-63. Three-line state: active US assignment (line 61), new all-regions comment (line 62), and the stale #os.environ["LANGFUSE_BASE_URL"] = "https://cloud.langfuse.com" # 🇪🇺 EU region (line 63). The diff in this file only shows a + for the new comment — no matching - for the EU line.
4. The published docs page at /guides/cookbook/integration_weco is generated from content/guides/cookbook/integration_weco.mdx, so web readers see a different snippet than .ipynb users and than readers of the /integrations/other/weco page.

Why existing code doesn't prevent it

There is no lint/test that cross-checks sibling files' code blocks for consistency, so a search-and-replace that is inconsistent across ~230 files slipped through review.

Fix

Three one-line deletes, each mirroring how the sibling files in the same PR handled the replacement:

• content/integrations/agentic-data-stack.mdx — delete line 54 (# US region).
• content/integrations/other/librechat.mdx — delete line 40 (# 🇺🇸 US Data Region).
• content/guides/cookbook/integration_weco.mdx — delete line 63 (#os.environ["LANGFUSE_BASE_URL"] = "https://cloud.langfuse.com" # 🇪🇺 EU region).

Severity: nit — purely cosmetic, but fixes a reader-facing inconsistency this PR itself created, and aligns the three files with the pattern the rest of the PR already established.

[claude]

🔴 The two new Japan launch blog posts (content/blog/2026-04-27-langfuse-cloud-japan.mdx:19 and content/blog/2026-04-27-langfuse-cloud-japan-jp.mdx:19) announce that Langfuse Cloud Japan is live today and link readers to /jp-cloud as the landing page, but the /jp-cloud marketing page and its components were NOT updated in this PR: it still renders a "Coming Soon" pill (components/jp-cloud/JpCloudHero.tsx:81), its only CTA is "Join our Japan Mailing List" (JpCloudHero.tsx:124-126, JpCloudCTA.tsx:52-55), and content/marketing/jp-cloud.mdx:3 still describes the page as a waitlist for an upcoming region. On merge day every reader of the launch announcement will click through to a page that contradicts the announcement. Fix: either update /jp-cloud in this PR (drop the Coming Soon badge, swap the waitlist CTA for a link to https://jp.cloud.langfuse.com or the /cloud region selector) or retarget the blog links to https://jp.cloud.langfuse.com / /cloud until the marketing page is re-skinned.

Extended reasoning...

What the bug is

This PR adds two launch blog posts that unambiguously position Japan Cloud as live and direct readers to /jp-cloud as the product landing page:

• EN post at content/blog/2026-04-27-langfuse-cloud-japan.mdx:19: "Today we're launching Langfuse Cloud Japan, a dedicated cloud region hosted in Japan…"
• JP post at content/blog/2026-04-27-langfuse-cloud-japan-jp.mdx:19: "本日、Langfuse Cloud Japan を公開します"
• Both posts also link to /jp-cloud from the "Getting started" list around line 53.

The target page /jp-cloud (rendered by content/marketing/jp-cloud.mdx → components/jp-cloud/*) was not touched by this PR. I verified by reading the current tree:

• content/marketing/jp-cloud.mdx:3 — OG description still says "Langfuse Cloud is coming to Japan. Join the waitlist for the Japan data region".
• components/jp-cloud/JpCloudHero.tsx:81 — still renders a "Coming Soon" gradient pill.
• components/jp-cloud/JpCloudHero.tsx:124-126 — hero's only CTA is "Join our Japan Mailing List".
• components/jp-cloud/JpCloudCTA.tsx:44-56 — bottom section is titled "Join our Japan mailing list for updates on the cloud region launch" with the mailing-list form as the sole action.
• None of content/marketing/jp-cloud.mdx or components/jp-cloud/* appears in the 236-file diff.

Why existing code doesn't prevent it

lib/blog-index.ts sorts posts by date with no date-cutoff filter, so both posts render at the top of /blog immediately on merge — there is no gating that could hide the announcement until /jp-cloud is re-skinned. The PR also already adds a Japan card to the /cloud region selector (app/cloud/[[...path]]/page.tsx:41-45) and updates other /security surfaces to mention Japan, so the omission of /jp-cloud is a gap in the same launch work rather than a deliberate phasing.

Why this is PR-introduced (not pre-existing)

Before this PR there was no public Langfuse surface claiming Japan was live, so the /jp-cloud waitlist page was internally consistent. This PR is the change that introduces the contradiction: it adds two announcement pages that both (a) state the region is live today and (b) choose /jp-cloud as their call-to-action target.

Impact

On merge day, every reader of the launch blog lands on a page that directly contradicts the announcement they just read. The "Coming Soon" pill and mailing-list CTA actively suggest the region is not available, while the blog says it is. There is no link from /jp-cloud to https://jp.cloud.langfuse.com or to the region selector at /cloud, so readers have no next step beyond signing up for a waitlist for a product that is already launched.

Step-by-step proof

1. PR merges. Both new blog posts are now live at /blog/2026-04-27-langfuse-cloud-japan and /blog/2026-04-27-langfuse-cloud-japan-jp (no date filter in lib/blog-index.ts).
2. A reader visits /blog, sees "Langfuse Cloud Japan Region" at the top, opens it.
3. Lead paragraph at :19 reads "Today we're launching Langfuse Cloud Japan". Reader clicks the inline link.
4. They land on /jp-cloud. Hero renders the "Coming Soon" pill (JpCloudHero.tsx:81). The only hero CTA (JpCloudHero.tsx:124-126) is "Join our Japan Mailing List". Scrolling further, the waitlist section (JpCloudCTA.tsx:44-56) repeats "Join our Japan mailing list for updates on the cloud region launch".
5. The OG/SEO description (content/marketing/jp-cloud.mdx:3) still literally says Japan is "coming" and invites the reader to the waitlist.
6. Reader has no in-page path to jp.cloud.langfuse.com or /cloud. The announcement page and its own linked destination disagree.

How to fix

Two equally acceptable options:

1. Update /jp-cloud in this PR. Remove the "Coming Soon" pill at components/jp-cloud/JpCloudHero.tsx:81, replace the "Join our Japan Mailing List" CTA at JpCloudHero.tsx:124-126 and JpCloudCTA.tsx:52-55 with a primary "Go to jp.cloud.langfuse.com" / "Select region at /cloud" button, and rewrite content/marketing/jp-cloud.mdx:3 so the description reflects the launched region.
2. Retarget the blog links. Change the /jp-cloud links at EN :19 and :53 and JP :19 and :53 to https://jp.cloud.langfuse.com (or /cloud, whose region selector already has the new jp card added by this PR at app/cloud/[[...path]]/page.tsx:41-45). This keeps /jp-cloud as-is until it's re-skinned in a follow-up PR.

Severity: normal. No compile or functional break, but on the highest-visibility launch surface the PR creates, the announcement page contradicts the page it itself chose to link to.

[claude]

🟡 The new JP data migration guide at content/guides/cookbook/example_data_migration-jp.mdx is not listed in content/guides/cookbook/meta.json, which fumadocs uses as the authoritative ordered sidebar list. All 49 other cookbook files (including the English example_data_migration at line 8) are listed; this new JP translation is the sole exception, so the page is reachable by URL but invisible in the cookbook navigation. Fix: add "example_data_migration-jp" to the pages array in meta.json, ideally next to the existing "example_data_migration" entry.

Extended reasoning...

What the bug is

This PR adds a new Japanese translation of the data migration cookbook at content/guides/cookbook/example_data_migration-jp.mdx (along with its notebook cookbook/example_data_migration-jp.ipynb and a new route entry in cookbook/_routes.json). The page has a proper frontmatter including sidebarTitle: データ移行スクリプト, signalling it is intended to appear in the sidebar. However, content/guides/cookbook/meta.json — the file fumadocs uses to determine the cookbook sidebar — was not updated.

Why this matters for navigation

The pages array in content/guides/cookbook/meta.json is an explicit ordered list with no "..." rest marker. fumadocs treats such a list as the authoritative sidebar: any MDX file on disk that is not named in the array is reachable by URL but will not appear in the sidebar. Confirmed by inspection: every other .mdx/.md file in content/guides/cookbook/ is listed in the array (including the English sibling example_data_migration at line 8), with example_data_migration-jp being the only exception introduced by this PR.

Compounding orphan problem

Nothing else in this PR links to the new JP guide either. The two launch blog posts (content/blog/2026-04-27-langfuse-cloud-japan.mdx and its JP translation) link only to generic /docs for "Migrating to Langfuse Cloud Japan", and the JP cookbook file itself does not include a BlogLanguageSwitcher equivalent linking back to the English migration guide. So after this PR, the only discovery path to /guides/cookbook/example_data_migration-jp is typing the URL directly — it is orphaned from all in-site navigation.

Step-by-step proof

1. A Japanese user follows the migration link in the JP launch blog post (/blog/2026-04-27-langfuse-cloud-japan-jp), which points at /docs.
2. They don't find JP-specific migration content on /docs, so they navigate to the Cookbook sidebar expecting to find a translated migration guide (the cookbook is where the English migration guide lives).
3. The sidebar is rendered from content/guides/cookbook/meta.json pages array. Because the array has no "..." rest marker and does not contain example_data_migration-jp, the JP page is not rendered in the sidebar — only the English example_data_migration entry is visible.
4. The user concludes no JP translation exists and either falls back to the English guide or gives up. The translated page that was shipped in this PR is effectively unreachable via normal navigation, defeating its purpose.

Fix

One-line addition to content/guides/cookbook/meta.json, placed next to the existing English entry:

    "example_data_migration",
    "example_data_migration-jp",

Severity

Nit — the URL still resolves and the page renders fine when visited directly; this is purely a discoverability regression. But the fix is a one-line addition that aligns with how every other cookbook file in this directory is treated, and it ensures the translation actually appears in the navigation it was built for.

[claude]

🟡 The two new Japan launch blog posts link 'Migrating to Langfuse Cloud Japan' / '移行' to a placeholder /docs (EN: lines 51 & 61; JP: lines 55 & 60), but this same PR creates the authoritative JP migration cookbook at content/guides/cookbook/example_data_migration-jp.mdx and the EN sibling example_data_migration.mdx already exists. Point the EN post at /guides/cookbook/example_data_migration and the JP post at /guides/cookbook/example_data_migration-jp so launch-day readers clicking 'migrate' actually land on migration guidance instead of the generic docs home.

Extended reasoning...

What the bug is

The two new Japan launch blog posts introduced in this PR each carry two links labelled 'Migrating to Langfuse Cloud Japan' / 'Langfuse Cloud Japan への移行' / '移行' that all point at the generic /docs home:

• content/blog/2026-04-27-langfuse-cloud-japan.mdx:51 — - [Migrating to Langfuse Cloud Japan](/docs)
• content/blog/2026-04-27-langfuse-cloud-japan.mdx:61 — [migrate](/docs) in the 'Our commitment to Japan' paragraph
• content/blog/2026-04-27-langfuse-cloud-japan-jp.mdx:55 — - [Langfuse Cloud Japan への移行](/docs)
• content/blog/2026-04-27-langfuse-cloud-japan-jp.mdx:60 — [移行](/docs) in the 'これから' closing paragraph

Why this is clearly a placeholder (not an intentional target)

This PR itself creates content/guides/cookbook/example_data_migration-jp.mdx (935 lines, an authoritative JP translation of the migration guide, full SDK v4 migration script covering score configs, custom models, prompts, observations, scores, and datasets). The English sibling content/guides/cookbook/example_data_migration.mdx already exists and is referenced as the canonical migration resource from content/security/hipaa.mdx:13 and from the new content/security/data-regions.mdx note about switching regions. So the EN post has a real, correct target (/guides/cookbook/example_data_migration), and the JP post has the exact JP-authored equivalent (/guides/cookbook/example_data_migration-jp) — both produced within this PR.

Additionally, the other four bullets in the same 'Getting started' list all point at specific targets (/jp-cloud, /docs, /security, /talk-to-us, the mailing-list form), and the list already contains a separate 'Getting Started' bullet pointing at /docs. Having a second 'Migrating' bullet that also resolves to /docs is therefore redundant — a clear tell that the author meant to fill in the migration-cookbook URL and didn't.

Why existing code doesn't prevent it

/docs is a real route, so no link-checker flags it. There is no test cross-referencing blog-post CTAs against companion guides introduced in the same PR.

Impact

The JP-language post is exactly the surface whose readers are most likely to click 'migrate' (they're reading the Japan launch announcement, which explicitly calls out EU→JP / US→JP migration as a primary use case). Landing them on the generic /docs home — with no breadcrumb to the JP migration cookbook the same PR ships — creates an immediate friction point for the launch's most strategically relevant reader segment. Severity is nit because the link resolves (no 404), but this is a trivial, high-signal fix worth doing before launch.

Step-by-step proof

1. Reader opens /blog/2026-04-27-langfuse-cloud-japan-jp on 2026-04-27 (launch day).
2. Scans to the 'Getting started / 使い始める' list at line 51-56 (JP file line 55).
3. Clicks 'Langfuse Cloud Japan への移行' expecting a migration how-to.
4. Router resolves /docs → the docs landing page, which has no JP migration-specific content and no prominent link to /guides/cookbook/example_data_migration-jp.
5. Reader now has to navigate manually to Guides → Cookbook → example_data_migration-jp to find the content they were promised — despite the file literally existing in this PR at content/guides/cookbook/example_data_migration-jp.mdx.
6. The inline [移行](/docs) in the closing 'これから' paragraph (line 60) plays out the same way.
7. Same user journey, same miss, on the EN post at /blog/2026-04-27-langfuse-cloud-japan (lines 51 and 61).

How to fix

Four one-line href edits:

• content/blog/2026-04-27-langfuse-cloud-japan.mdx line 51: [Migrating to Langfuse Cloud Japan](/guides/cookbook/example_data_migration)
• content/blog/2026-04-27-langfuse-cloud-japan.mdx line 61: [migrate](/guides/cookbook/example_data_migration)
• content/blog/2026-04-27-langfuse-cloud-japan-jp.mdx line 55: [Langfuse Cloud Japan への移行](/guides/cookbook/example_data_migration-jp)
• content/blog/2026-04-27-langfuse-cloud-japan-jp.mdx line 60: [移行](/guides/cookbook/example_data_migration-jp)