From 7e50165eabdb22019f7da326e567db8029f9ad92 Mon Sep 17 00:00:00 2001 From: Manoel Aranda Neto Date: Wed, 27 May 2026 16:59:31 +0200 Subject: [PATCH] chore: add elixir docs coverage --- transformation-config/commandments.yaml | 13 +++++++++ .../skills/error-tracking/config.yaml | 6 +++++ .../skills/integration/config.yaml | 9 +++++++ .../description-elixir-docs-only.md | 27 +++++++++++++++++++ .../instrument-error-tracking/config.yaml | 1 + .../instrument-error-tracking/description.md | 6 ++--- .../instrument-feature-flags/description.md | 4 +-- .../instrument-integration/config.yaml | 2 ++ .../instrument-integration/description.md | 6 ++--- .../instrument-product-analytics/config.yaml | 2 ++ .../description.md | 6 ++--- 11 files changed, 71 insertions(+), 11 deletions(-) create mode 100644 transformation-config/skills/integration/description-elixir-docs-only.md diff --git a/transformation-config/commandments.yaml b/transformation-config/commandments.yaml index 53c8f8c0..ddc8d287 100644 --- a/transformation-config/commandments.yaml +++ b/transformation-config/commandments.yaml @@ -79,6 +79,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 0cba0776..2042f4d3 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 ac3ccfc6..e6bdc2b7 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: swift example_paths: basics/swift display_name: Swift (iOS/macOS) 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 00000000..812483ae --- /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 0d7c6e5d..5b49aa09 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.md diff --git a/transformation-config/skills/omnibus/instrument-error-tracking/description.md b/transformation-config/skills/omnibus/instrument-error-tracking/description.md index cccc527a..ed4afd2f 100644 --- a/transformation-config/skills/omnibus/instrument-error-tracking/description.md +++ b/transformation-config/skills/omnibus/instrument-error-tracking/description.md @@ -2,15 +2,15 @@ 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, 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, Android, and Hono. ## Instructions Follow these steps IN ORDER: STEP 1: Analyze the codebase and detect the platform. - - Look for dependency files (package.json, 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) to determine the package manager. + - Look for dependency files (package.json, 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, 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 51be2247..249fb1a7 100644 --- a/transformation-config/skills/omnibus/instrument-feature-flags/description.md +++ b/transformation-config/skills/omnibus/instrument-feature-flags/description.md @@ -9,8 +9,8 @@ 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, 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) to determine the package manager. + - Look for dependency files (package.json, 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, 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 5ea1583a..5e58f459 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 # PHP - https://posthog.com/docs/libraries/laravel.md - https://posthog.com/docs/libraries/php.md diff --git a/transformation-config/skills/omnibus/instrument-integration/description.md b/transformation-config/skills/omnibus/instrument-integration/description.md index 58be1a06..3f6a33da 100644 --- a/transformation-config/skills/omnibus/instrument-integration/description.md +++ b/transformation-config/skills/omnibus/instrument-integration/description.md @@ -2,15 +2,15 @@ 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: Next.js, React, React Router, Vue, Nuxt, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Android, Swift, 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, Elixir, Android, Swift, 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, 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) to determine the package manager. + - Look for dependency files (package.json, 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, 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 2caf5063..a494ef2d 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 # PHP - https://posthog.com/docs/libraries/laravel.md - https://posthog.com/docs/libraries/php.md diff --git a/transformation-config/skills/omnibus/instrument-product-analytics/description.md b/transformation-config/skills/omnibus/instrument-product-analytics/description.md index 9ac07d62..a15c6eb5 100644 --- a/transformation-config/skills/omnibus/instrument-product-analytics/description.md +++ b/transformation-config/skills/omnibus/instrument-product-analytics/description.md @@ -2,15 +2,15 @@ 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: Next.js, React Router, Nuxt, Vue, TanStack Start, SvelteKit, Astro, Angular, Django, Flask, FastAPI, Laravel, PHP, Ruby on Rails, Android, iOS, 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, Elixir, Android, iOS, 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, 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) to determine the package manager. + - Look for dependency files (package.json, 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, 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.)