chore: merge main and bump plugin version

2026-09-14 20:00:05 +08:00 · 2026-07-21 10:20:12 +02:00
parent 41eb68de91 abe69fac6b
commit e569195a41
8 changed files with 16 additions and 81 deletions
@@ -1,7 +1,7 @@
 {
  "name": "langfuse",
  "description": "Skills for working with Langfuse, the open-source LLM engineering platform for tracing, prompt management, and evaluation.",
-  "version": "1.3.0",
+  "version": "1.4.1",
  "author": {
    "name": "Langfuse",
    "email": "support@langfuse.com"
@@ -1,6 +1,6 @@
 {
  "name": "langfuse",
-  "version": "1.3.0",
+  "version": "1.4.1",
  "description": "Skills for working with Langfuse, the open-source LLM engineering platform for tracing, prompt management, and evaluation.",
  "author": {
    "name": "Langfuse",
@@ -33,7 +33,7 @@
      "Set up Langfuse tracing in this app.",
      "Inspect Langfuse traces for recent failures.",
      "Migrate prompts into Langfuse.",
-      "Prepare this application and its Langfuse project for the v4 platform migration. Fetch and follow https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/v4-project-migration.md, https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/sdk-upgrade.md, and https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/trace-evaluator-upgrade.md. Implement and validate applicable code and project changes, then report UI-only or blocked steps."
+      "Prepare this application and its Langfuse project for the v4 platform migration."
    ],
    "websiteURL": "https://langfuse.com",
    "privacyPolicyURL": "https://langfuse.com/privacy",
@@ -1,7 +1,7 @@
 {
  "name": "langfuse",
  "displayName": "Langfuse",
-  "version": "1.3.0",
+  "version": "1.4.1",
  "description": "Skills for working with Langfuse — the open-source LLM engineering platform for tracing, prompt management, and evaluation.",
  "author": {
    "name": "Langfuse",
@@ -36,9 +36,8 @@ Follow these principles for ALL Langfuse work:
 - creating a prompt or changing any part of an existing prompt, including small edits and debugging/tuning: references/prompt-engineering.md
 - capturing user feedback (thumbs, ratings, implicit signals) as scores on traces: references/user-feedback.md
 - further tips on using the Langfuse CLI: references/cli.md
- upgrading or migrating Langfuse SDKs to the latest version: references/sdk-upgrade.md
 - upgrading legacy trace-level evaluators and their application instrumentation to observation-level evaluators: references/trace-evaluator-upgrade.md
- preparing an application and Langfuse project for the v4 platform migration: references/sdk-upgrade.md and references/v4-project-migration.md
+- preparing an application and Langfuse project for the v4 platform migration: references/v4-project-migration.md
 - judge calibration (LLM-as-a-Judge reliability, simple accuracy checks, advanced split-based validation, confusion matrices, and metric ingestion): references/judge-calibration.md
 - systematic error analysis — reading traces, building failure taxonomy, deciding what to fix: references/error-analysis.md
 - setting up CI/CD experiment gates with `langfuse/experiment-action`: references/ci-cd.md
@@ -1,70 +0,0 @@
---
-name: langfuse-sdk-upgrade
-description: Upgrade Langfuse SDKs and instrumentation to current versions. Use when migrating Python SDK v2/v3 to v4, JS/TS SDK v3/v4 to v5, or preparing application code for the Langfuse v4 platform.
-metadata:
-  required_access:
-    - CODEBASE
-    - LANGFUSE_PROJECT_SCRIPT
---
-
-# Langfuse SDK upgrade
-
-## Sources of truth
-
-Fetch the applicable pages in full before editing. Do not implement from this file or memory alone.
-
- [Langfuse v4 overview](https://langfuse.com/docs/v4)
- [Python v3 to v4](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4)
- [JS/TS v4 to v5](https://langfuse.com/docs/observability/sdk/upgrade-path/js-v4-to-v5)
- [Direct OpenTelemetry setup](https://langfuse.com/integrations/native/opentelemetry)
- [Observations API](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
- [Metrics API](https://langfuse.com/docs/metrics/features/metrics-api)
-
-Use the exact minimum versions and migration requirements in the current docs. Prefer the latest stable release in the required major unless the repository has an explicit compatibility constraint.
-
-## Workflow
-
-### 1. Inventory before editing
-
- Find every Langfuse SDK, integration package, direct OpenTelemetry exporter, initialization site, instrumentation wrapper, trace-update call, and direct Langfuse API call across the whole repository.
- Record the installed and resolved versions for every application/package. Include lockfiles, workspace overrides, and peer dependencies.
- Identify tests, examples, workers, and scripts that initialize Langfuse independently; do not assume the main application is the only ingestion path.
- If this is part of the v4 platform migration, also follow `references/v4-project-migration.md`. When its handoff includes active legacy trace-level evaluators, follow `references/trace-evaluator-upgrade.md` for the code changes. Do not infer evaluator requirements during a standalone SDK upgrade.
-
-### 2. Upgrade the ingestion path
-
- Update dependencies with the repository's package manager and follow every applicable item in the current SDK migration guide.
- For direct OpenTelemetry ingestion, apply the current v4 ingestion header and attribute-propagation requirements from the docs.
- Preserve deliberate custom span-export behavior. Verify whether the application relies on non-LLM spans before accepting a new default span filter.
- Replace removed or deprecated tracing APIs using the current guide. Do not retain deprecated trace input/output setters unless an active legacy trace evaluator still needs them during a staged cutover.
- Keep correlating attributes inside the documented propagation scope so the target observations receive the attributes used by filters and analytics.
-
-### 3. Upgrade trace-level evaluators
-
-If the project upgrade workflow includes active legacy trace-level evaluators, follow `references/trace-evaluator-upgrade.md`. It owns target-observation selection, filter and variable translation, instrumentation changes, score-cardinality checks, and the project-side handoff.
-
-Do not consider the evaluator code handoff complete until every evaluator variable and retained filter can be satisfied by one stable observation. Do not copy an entire trace into metadata to avoid selecting the correct observation.
-
-### 4. Replace deprecated API usage
-
- Search both SDK resource namespaces and raw HTTP paths; include generated clients, fixtures, shell scripts, dashboards, and data pipelines.
- Use the current SDK migration guide and API docs to replace transitional aliases and legacy Observations, Scores, or Metrics routes.
- Check deployment availability before changing a self-hosted client to an endpoint that is Cloud-only or not yet available in that deployment.
- Update pagination, selected field groups, filters, and response parsing together with the endpoint. A path-only replacement is not a complete migration.
-
-### 5. Verify
-
- Run the repository's focused formatting, type, lint, and test checks.
- Exercise every changed ingestion path with representative application behavior. Confirm observation hierarchy, target observation input/output/context, propagated attributes, and absence of unexpected dropped spans.
- If Langfuse project access is available, inspect the resulting observations and verify that each new evaluator rule matches the intended observation and can populate every variable.
- Do not claim live verification when credentials or a runnable environment are unavailable. Report the exact remaining check.
-
-## Completion report
-
-Report:
-
- exact SDK/package versions before and after
- instrumentation and API call sites changed
- for a v4 platform migration, evaluator-contract code changes and any legacy evaluator that still temporarily requires trace input/output
- verification run and observed result
- project or UI actions that remain
@@ -37,7 +37,7 @@ Discover the current unstable API schema before use. Use unstable evaluation-rul

 ## 2. Confirm v4 instrumentation

-The SDK upgrade should already have happened. Inspect the repository and a representative newly ingested trace to confirm the resolved SDK or OpenTelemetry path follows `references/sdk-upgrade.md`; do not infer readiness from a dependency declaration alone.
+The SDK upgrade should already have happened. Inspect the repository and a representative newly ingested trace to confirm the resolved SDK or OpenTelemetry path follows the applicable guide under [SDK upgrade paths](https://langfuse.com/docs/observability/sdk/upgrade-path); do not infer readiness from a dependency declaration alone.

 V4 SDK migration can change the tracing shape. By default, complete and verify the SDK upgrade before creating successor rules. Migrating against pre-upgrade data is possible but not recommended: link the user to the applicable SDK upgrade guide and proceed only after they explicitly confirm the selected observations, fields, and selectors will remain valid.

@@ -16,7 +16,7 @@ Fetch the applicable pages before taking action:

 - [Langfuse v4 overview](https://langfuse.com/docs/v4)
 - [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)
- [SDK upgrade workflow](https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/sdk-upgrade.md)
+- [SDK upgrade paths](https://langfuse.com/docs/observability/sdk/upgrade-path)
 - [Trace-level evaluator upgrade workflow](https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/trace-evaluator-upgrade.md)
 - [Evaluator migration guide](https://langfuse.com/faq/all/llm-as-a-judge-migration)
 - [Observation evaluator context](https://langfuse.com/docs/evaluation/evaluation-methods/llm-as-a-judge#observation-evaluator-context)
@@ -38,7 +38,7 @@ Discover the current API or tool schema before writes; the evaluator endpoints a

 ## 2. Upgrade SDKs and instrumentation

- For a coding agent with repository access, fetch and follow the [SDK upgrade workflow](https://raw.githubusercontent.com/langfuse/skills/main/skills/langfuse/references/sdk-upgrade.md) before declaring the platform migration ready.
+- For a coding agent with repository access, execute the repository-wide SDK upgrade in the steps below — using the version-specific breaking-changes guide under [SDK upgrade paths](https://langfuse.com/docs/observability/sdk/upgrade-path) as the docs reference — before declaring the platform migration ready.
 - Inventory every Langfuse SDK, integration package, direct OpenTelemetry exporter, initialization site, and lockfile across the repository. Upgrade each ingestion path to the latest stable release in the major required by the current v4 migration docs, unless the repository has a documented compatibility constraint.
 - Apply every applicable SDK migration step, update removed tracing APIs, and replace deprecated Observations, Scores, and Metrics API routes using the current docs. A dependency-only update is incomplete.
 - Use the evaluator migration contract below to consolidate all required evaluation input, output, metadata, tool calls, and propagated filter attributes onto the single target observation.
@@ -86,12 +86,18 @@ If the available project interface cannot read or update a legacy rule, provide

 ## 6. Migrate exports

+Changing the export source is a breaking change for every downstream consumer, not a settings toggle. Before proposing or making any source change, explain the concrete consequences for each configured integration and obtain the user's explicit confirmation that downstream owners are prepared.
+
 - Inventory configured Blob Storage, Mixpanel, PostHog, and other export integrations in **Project Settings > Integrations**.
+- Spell out what the source change does per integration before touching it:
+  - **Blob Storage:** the exported tables and file paths change. Legacy writes `traces` and `observations` files; enriched writes `observations_v2` under a new directory prefix, and the separate `traces` file is no longer produced in enriched-only mode. Column sets differ per the [export field reference](https://langfuse.com/docs/api-and-data-platform/features/blob-storage-export-fields#enriched-vs-legacy-differences), so loaders, warehouse table schemas, trace-observation joins, and dashboards across the full data pipeline must be updated — not just the integration setting.
+  - **Mixpanel and PostHog:** the source determines which events and properties are sent, so dashboards, transformations, funnels, and alerts built on the legacy events in those systems are affected and must be revalidated.
+  - **Dual mode** (`legacy and enriched observations`) creates duplicate records by design. Warn that counts, costs, and metrics in downstream systems will be inflated until consumers deduplicate or the transition completes.
 - For Blob Storage, inspect or update the integration through the API when organization-scoped credentials and the current schema are available. Otherwise direct the user to [Blob Storage settings](https://cloud.langfuse.com/project/~/settings/integrations/blobstorage).
 - For Mixpanel and PostHog, use the UI and the linked migration guides. Do not claim an API migration path that the current interface does not provide.
- Prefer the documented dual-export transition: enable legacy plus enriched observations, update and validate downstream consumers against the field reference, then switch to enriched observations only.
+- Follow the documented dual-export transition: enable legacy plus enriched observations, update and validate downstream consumers against the field reference, then switch to enriched observations only. Never switch a legacy integration directly to enriched-only while downstream consumers are unvalidated.
 - Do not overwrite bucket credentials, schedules, prefixes, file formats, field groups, or integration secrets while changing the export source.
- Treat the downstream consumer update as part of the migration. A source toggle without validating queries, joins, dashboards, and field parsing is incomplete.
+- Treat the downstream consumer update as part of the migration. A source toggle without validating queries, joins, dashboards, and field parsing is incomplete; report this area as `manual action`, not `ready`, until the user confirms consumers handle the new schema.

 ## 7. Report readiness