diff --git a/transformation-config/commandments.yaml b/transformation-config/commandments.yaml index 9b72888..0d2ee7f 100644 --- a/transformation-config/commandments.yaml +++ b/transformation-config/commandments.yaml @@ -91,6 +91,19 @@ commandments: - Call `IdentifyAsync` for known users and put PII such as email in person properties, not in event properties - Use `CaptureException(exception, distinctId, properties, groups, flags)` for handled exceptions; automatic exception capture is not available in the .NET SDK yet + elixir: + - posthog-elixir is installed as the `posthog` Hex package; add `{:posthog, "~> 2.0"}` to `mix.exs` and run `mix deps.get` + - Configure PostHog in application config using `api_host`, `api_key`, and `in_app_otp_apps`; read secrets from environment or runtime config, never hardcode them + - In tests, set `test_mode` to true so events are dropped instead of sent to PostHog + - For Phoenix or Plug apps, add `PostHog.Integrations.Plug` before the router so request context is attached to captured events and errors + - Server-side captures must include a stable `distinct_id` matching frontend identify calls, or set it once per process/request with `PostHog.set_context/1` + - Remember `PostHog.set_context/1` uses Logger metadata and is process-scoped; set context in the request, job, or Task process that captures the event + - For new feature flag code, prefer `PostHog.FeatureFlags.evaluate_flags/1` once per user/request, then read values from `PostHog.FeatureFlags.Evaluations` + - To attribute captures to feature flags, call `PostHog.FeatureFlags.set_in_context/1` with the evaluated snapshot, optionally filtered with `only_accessed/1` or `only/2` + - Avoid deprecated feature flag helpers such as `check/2`, `check!/2`, `get_feature_flag_result/2`, and `get_feature_flag_result!/2` in new code + - Error tracking is enabled by default through Logger; set `in_app_otp_apps`, `capture_level`, and `metadata` to improve error grouping and context + - For source context in releases, enable source code context and run `mix posthog.package_source_code` before `mix release` + aspnetcore: - In ASP.NET Core apps, prefer `builder.AddPostHog()` from `PostHog.AspNetCore` and inject `IPostHogClient` from dependency injection instead of manually constructing clients in controllers - Configure ASP.NET Core apps with the `PostHog` configuration section or environment variable fallbacks such as `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST` diff --git a/transformation-config/skills/error-tracking/config.yaml b/transformation-config/skills/error-tracking/config.yaml index bd6b1b1..6674e00 100644 --- a/transformation-config/skills/error-tracking/config.yaml +++ b/transformation-config/skills/error-tracking/config.yaml @@ -93,6 +93,12 @@ variants: - https://posthog.com/docs/error-tracking/installation/dotnet.md - https://posthog.com/docs/libraries/dotnet.md + - id: elixir + display_name: Elixir + tags: [elixir] + docs_urls: + - https://posthog.com/docs/error-tracking/installation/elixir.md + - id: angular display_name: Angular tags: [angular, javascript] diff --git a/transformation-config/skills/integration/config.yaml b/transformation-config/skills/integration/config.yaml index fb9795a..56949f1 100644 --- a/transformation-config/skills/integration/config.yaml +++ b/transformation-config/skills/integration/config.yaml @@ -201,6 +201,15 @@ variants: docs_urls: - https://posthog.com/docs/libraries/ruby.md + - id: elixir + type: docs-only + template: description-elixir-docs-only.md + display_name: Elixir + description: PostHog integration for Elixir and Phoenix applications using the posthog SDK + tags: [elixir, phoenix, plug] + docs_urls: + - https://posthog.com/docs/libraries/elixir.md + - id: go type: docs-only template: description-go-docs-only.md diff --git a/transformation-config/skills/integration/description-elixir-docs-only.md b/transformation-config/skills/integration/description-elixir-docs-only.md new file mode 100644 index 0000000..812483a --- /dev/null +++ b/transformation-config/skills/integration/description-elixir-docs-only.md @@ -0,0 +1,27 @@ +# PostHog integration for {display_name} + +This skill helps you add PostHog analytics to {display_name} applications using the official PostHog Elixir SDK documentation. + +## Instructions + +1. Detect the existing Elixir app structure. Check `mix.exs`, `mix.lock`, `config/`, `lib/`, `application.ex`, Phoenix endpoint/router files, Plug pipelines, and existing Logger/error handling. +2. Read the reference files below before changing code. They are the source of truth for SDK installation, configuration, event capture, context, feature flags, group analytics, and error tracking. +3. Install the SDK by adding `{:posthog, "~> 2.0"}` to `mix.exs` and running `mix deps.get`, unless the project already uses a newer compatible version. +4. Configure PostHog through `config/config.exs` or runtime config using environment variables for `api_key` and `api_host`. Never hardcode secrets. +5. Add captures at meaningful request, job, or business-action boundaries. Use a stable `distinct_id` that matches the frontend/user identity. +6. Verify with the project's normal Mix commands, such as `mix test`, `mix format --check-formatted`, or the repository's existing checks. + +## Reference files + +{references} + +## Key principles + +- **Environment variables**: Always use environment variables for PostHog keys. Never hardcode them. +- **Minimal changes**: Add PostHog code alongside existing integrations. Don't replace or restructure existing code. +- **Match the docs**: Follow the Elixir reference's installation, configuration, capture, context, feature flag, and error tracking patterns exactly. +- **Analytics contract**: Treat event names, property names, and feature flag keys as part of an analytics contract. Reuse existing names and patterns found in the project. When introducing new ones, make them clear, descriptive, and consistent with existing conventions. + +## Framework guidelines + +{commandments} diff --git a/transformation-config/skills/omnibus/instrument-error-tracking/config.yaml b/transformation-config/skills/omnibus/instrument-error-tracking/config.yaml index a6d4d50..8a2357d 100644 --- a/transformation-config/skills/omnibus/instrument-error-tracking/config.yaml +++ b/transformation-config/skills/omnibus/instrument-error-tracking/config.yaml @@ -29,6 +29,7 @@ variants: - https://posthog.com/docs/error-tracking/installation/go.md - https://posthog.com/docs/error-tracking/installation/dotnet.md - https://posthog.com/docs/libraries/dotnet.md + - https://posthog.com/docs/error-tracking/installation/elixir.md - https://posthog.com/docs/error-tracking/installation/angular.md - https://posthog.com/docs/error-tracking/installation/svelte.md - https://posthog.com/docs/error-tracking/installation/nuxt-3-7.md diff --git a/transformation-config/skills/omnibus/instrument-error-tracking/description.md b/transformation-config/skills/omnibus/instrument-error-tracking/description.md index b2031f4..b8151d0 100644 --- a/transformation-config/skills/omnibus/instrument-error-tracking/description.md +++ b/transformation-config/skills/omnibus/instrument-error-tracking/description.md @@ -2,15 +2,17 @@ Use this skill to add PostHog error tracking that captures and monitors exceptions in your application. Use it after implementing features or reviewing PRs to ensure errors are tracked with full stack traces and source maps. If PostHog is not yet installed, this skill also covers initial SDK setup. Supports any platform or language. -Supported platforms: React, Next.js, Web (JavaScript), Node.js, Python, PHP, Ruby, Ruby on Rails, Go, Angular, Svelte, Nuxt, React Native, Flutter, iOS, Android, and Hono. +Supported platforms: React, Next.js, Web (JavaScript), Node.js, Python, PHP, Ruby, Ruby on Rails, Go, Elixir, Angular, Svelte, Nuxt, React Native, Flutter, iOS, Android, and Hono. ## Instructions Follow these steps IN ORDER: STEP 1: Analyze the codebase and detect the platform. - - Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, go.mod, Gemfile, composer.json, etc.) to determine the language and framework. - - Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved) to determine the package manager. + - + Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, go.mod, Gemfile, composer.json, mix.exs, etc.) to determine the language and framework. + - + Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved, mix.lock) to determine the package manager. - Check for existing PostHog setup (SDK initialization, env vars, etc.). If PostHog is already installed and initialized, skip to STEP 4. STEP 2: Research instrumentation. (Skip if PostHog is already set up.) diff --git a/transformation-config/skills/omnibus/instrument-feature-flags/description.md b/transformation-config/skills/omnibus/instrument-feature-flags/description.md index bf6809c..8b21103 100644 --- a/transformation-config/skills/omnibus/instrument-feature-flags/description.md +++ b/transformation-config/skills/omnibus/instrument-feature-flags/description.md @@ -9,8 +9,10 @@ Supported platforms: React, Next.js, React Native, Web (JavaScript), Node.js, Py Follow these steps IN ORDER: STEP 1: Analyze the codebase and detect the platform. - - Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, go.mod, Gemfile, composer.json, etc.) to determine the language and framework. - - Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved) to determine the package manager. + - + Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, go.mod, Gemfile, composer.json, mix.exs, etc.) to determine the language and framework. + - + Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved, mix.lock) to determine the package manager. - Check for existing PostHog setup (SDK initialization, env vars, etc.). If PostHog is already installed and initialized, skip to STEP 3. STEP 2: Research instrumentation. (Skip if PostHog is already set up.) diff --git a/transformation-config/skills/omnibus/instrument-integration/config.yaml b/transformation-config/skills/omnibus/instrument-integration/config.yaml index 7c6858d..e7b2cf9 100644 --- a/transformation-config/skills/omnibus/instrument-integration/config.yaml +++ b/transformation-config/skills/omnibus/instrument-integration/config.yaml @@ -76,6 +76,8 @@ variants: - https://posthog.com/docs/references/posthog-python.md # .NET - https://posthog.com/docs/libraries/dotnet.md + # Elixir + - https://posthog.com/docs/libraries/elixir.md # Go - https://posthog.com/docs/libraries/go.md # PHP diff --git a/transformation-config/skills/omnibus/instrument-integration/description.md b/transformation-config/skills/omnibus/instrument-integration/description.md index 999d9ad..25480ed 100644 --- a/transformation-config/skills/omnibus/instrument-integration/description.md +++ b/transformation-config/skills/omnibus/instrument-integration/description.md @@ -2,15 +2,17 @@ Use this skill to add the PostHog SDK to an application. Use it when setting up PostHog for the first time, or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration. Supports any framework or language. -Supported frameworks and languages: Next.js, React, React Router, Vue, Nuxt, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Go, Android, iOS, Swift, Flutter, React Native, Expo, Node.js, and vanilla JavaScript. +Supported frameworks and languages: Next.js, React, React Router, Vue, Nuxt, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Go, Elixir, Android, iOS, Swift, Flutter, React Native, Expo, Node.js, and vanilla JavaScript. ## Instructions Follow these steps IN ORDER: STEP 1: Analyze the codebase and detect the platform. - - Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, Gemfile, composer.json, go.mod, etc.) to determine the framework and language. - - Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved) to determine the package manager. + - + Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, Gemfile, composer.json, go.mod, mix.exs, etc.) to determine the framework and language. + - + Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved, mix.lock) to determine the package manager. - Check for existing PostHog setup. If PostHog is already installed and initialized, do not modify its code. Inform the user and skip to verification. STEP 2: Research integration. diff --git a/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml b/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml index 84c39f3..fd7efd2 100644 --- a/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml +++ b/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml @@ -67,6 +67,8 @@ variants: - https://posthog.com/docs/references/posthog-python.md # .NET - https://posthog.com/docs/libraries/dotnet.md + # Elixir + - https://posthog.com/docs/libraries/elixir.md # Go - https://posthog.com/docs/libraries/go.md # PHP diff --git a/transformation-config/skills/omnibus/instrument-product-analytics/description.md b/transformation-config/skills/omnibus/instrument-product-analytics/description.md index 6206c09..5b7d09d 100644 --- a/transformation-config/skills/omnibus/instrument-product-analytics/description.md +++ b/transformation-config/skills/omnibus/instrument-product-analytics/description.md @@ -2,15 +2,17 @@ Use this skill to add product analytics events (capture calls) that track meaningful user actions in new or changed code. Use it after implementing features or reviewing PRs to ensure key user behaviors are captured. If PostHog is not yet installed, this skill also covers initial SDK setup. Supports any framework or language. -Supported frameworks and languages: Next.js, React Router, Nuxt, Vue, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Go, Android, iOS, Flutter, React Native, Expo, and more. +Supported frameworks and languages: Next.js, React Router, Nuxt, Vue, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Go, Elixir, Android, iOS, Flutter, React Native, Expo, and more. ## Instructions Follow these steps IN ORDER: STEP 1: Analyze the codebase and detect the platform. - - Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, Gemfile, composer.json, go.mod, etc.) to determine the framework and language. - - Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved) to determine the package manager. + - + Look for dependency files (package.json, pubspec.yaml, Podfile, Package.swift, requirements.txt, Gemfile, composer.json, go.mod, mix.exs, etc.) to determine the framework and language. + - + Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, go.sum, pubspec.lock, Podfile.lock, Package.resolved, mix.lock) to determine the package manager. - Check for existing PostHog setup. If PostHog is already installed and initialized, skip to STEP 5. STEP 2: Research integration. (Skip if PostHog is already set up.)