Skip to content

The only tool you need to know what is happening and how to fix it.

php symfony otel added

dduxed2791fb3921
diff --git a/CLAUDE.md b/CLAUDE.md
index 616e34b1..90a28deb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1258,3 +1258,21 @@ type PaginationParams struct {
```typescript
const orderBy = `${sortState.field} ${sortState.direction}`
```
+
+### Adding a New Framework
+
+Every framework addition touches multiple files across backend, frontend, and docs. Use this checklist to avoid missing any:
+
+1. **Backend** — `backend/app/controllers/project.controller.go`: Add to `validFrameworks` map and update the validation error message
+2. **Frontend state** — `frontend/src/lib/state/projects.svelte.ts`: Add to `Framework` type union and `FRAMEWORK_LABELS` map
+3. **Frontend combobox** — `frontend/src/lib/components/framework-combobox.svelte`: Add entry with correct group (Go / JavaScript / PHP / etc.)
+4. **Frontend icon** — `frontend/src/lib/components/framework-icon.svelte`: Add icon mapping for the new framework value
+5. **Framework code** — `frontend/src/lib/utils/framework-code.ts`: Add install command, integration code snippet, label, code language, and testing routes
+6. **Connection page** — `frontend/src/routes/connection/+page.svelte`: Add highlight language mapping and install description
+7. **Dashboard page** — `frontend/src/routes/+page.svelte`: Add highlight language mapping
+8. **Docs sidebar** — `docs/pages/client/_meta.json`: Add navigation entry
+9. **Docs SDK selector** — `docs/components/SdkContext.jsx`: Add to `SDK_OPTIONS` array and `PATH_SDK_MAP` object
+10. **Docs framework picker** — `docs/components/FrameworkPicker.jsx`: Add card to `FRAMEWORKS` array
+11. **Docs icon** — `docs/public/`: Add framework icon (PNG, ~45x45)
+12. **Docs page** — `docs/pages/client/<framework>/`: Create `_meta.json` and `index.mdx`
+13. **Docs OTel language table** — `docs/pages/client/otel/index.mdx`: Add row if the framework uses OTLP
diff --git a/backend/app/controllers/project.controller.go b/backend/app/controllers/project.controller.go
index 3eb19cae..c41b7248 100644
--- a/backend/app/controllers/project.controller.go
+++ b/backend/app/controllers/project.controller.go
@@ -35,6 +35,8 @@ var validFrameworks = map[string]bool{
"remix": true,
"cloudflare": true,
"opentelemetry": true,
+ // PHP frameworks
+ "symfony": true,
}
// Project name validation regex: allows alphanumeric, spaces, hyphens, and underscores
@@ -82,7 +84,7 @@ func (p projectController) CreateProject(c *gin.Context) {
if !validFrameworks[request.Framework] {
traceway.CaptureMessage("Invalid framework received: " + request.Framework)
- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, nextjs, nestjs, express, remix, cloudflare, opentelemetry"})
+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, nextjs, nestjs, express, remix, cloudflare, opentelemetry, symfony"})
return
}
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsx
index b1a8dde9..d0b3be63 100644
--- a/docs/components/FrameworkPicker.jsx
+++ b/docs/components/FrameworkPicker.jsx
@@ -18,6 +18,14 @@ const FRAMEWORKS = [
href: "/client/cloudflare",
badge: "new",
},
+ {
+ value: "php-symfony",
+ label: "Symfony",
+ description: "Symfony framework with OpenTelemetry auto-instrumentation.",
+ icon: "/symfony.png",
+ href: "/client/symfony",
+ badge: "new",
+ },
{
value: "go-gin",
label: "Go Gin",
diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsx
index 9c0ade27..e3139f60 100644
--- a/docs/components/SdkContext.jsx
+++ b/docs/components/SdkContext.jsx
@@ -16,6 +16,7 @@ export const SDK_OPTIONS = [
{ value: 'js-generic', label: 'JS Generic' },
{ value: 'otel', label: 'OpenTelemetry (otel)' },
{ value: 'cloudflare', label: 'Cloudflare Workers' },
+ { value: 'php-symfony', label: 'Symfony' },
]
const STORAGE_KEY = 'traceway-docs-sdk'
@@ -34,6 +35,7 @@ const PATH_SDK_MAP = {
'svelte': 'js-svelte',
'otel': 'otel',
'cloudflare': 'cloudflare',
+ 'symfony': 'php-symfony',
}
const SdkContext = createContext({
diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsx
index 9b6d0fa4..891739ef 100644
--- a/docs/components/SdkSelector.jsx
+++ b/docs/components/SdkSelector.jsx
@@ -16,6 +16,8 @@ const SDK_QUICK_START = {
'js-svelte': '/client/svelte',
'js-generic': '/client/js-sdk',
'otel': '/client/otel',
+ 'cloudflare': '/client/cloudflare',
+ 'php-symfony': '/client/symfony',
}
export default function SdkSelector() {
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.json
index 9265f965..bcefba14 100644
--- a/docs/pages/client/_meta.json
+++ b/docs/pages/client/_meta.json
@@ -18,5 +18,6 @@
"svelte": "Svelte",
"js-sdk": "JS SDK Reference",
"otel": "OpenTelemetry",
- "cloudflare": "Cloudflare Workers"
+ "cloudflare": "Cloudflare Workers",
+ "symfony": "Symfony"
}
diff --git a/docs/pages/client/otel/index.mdx b/docs/pages/client/otel/index.mdx
index 07ad7c95..6e240b32 100644
--- a/docs/pages/client/otel/index.mdx
+++ b/docs/pages/client/otel/index.mdx
@@ -21,6 +21,7 @@ Any language with an OTel SDK can export to Traceway. Here are the most common o
| C# / .NET | [opentelemetry-dotnet](https://github.com/open-telemetry/opentelemetry-dotnet) | `dotnet add package OpenTelemetry` |
| Go | [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go) | `go get go.opentelemetry.io/otel` |
| Node.js | [opentelemetry-js](https://github.com/open-telemetry/opentelemetry-js) | `npm install @opentelemetry/sdk-node` |
+| PHP / Symfony | [opentelemetry-php](https://github.com/open-telemetry/opentelemetry-php) | `composer require open-telemetry/sdk` — see [Symfony guide](/client/symfony) |
| Cloudflare Workers | [workers-sdk](https://developers.cloudflare.com/workers/observability/otel/) | Built-in — see [Cloudflare guide](/client/otel-cloudflare) |
## Configuration
diff --git a/docs/pages/client/symfony/_meta.json b/docs/pages/client/symfony/_meta.json
new file mode 100644
index 00000000..8393d864
--- /dev/null
+++ b/docs/pages/client/symfony/_meta.json
@@ -0,0 +1,3 @@
+{
+ "index": "Quick Start"
+}
diff --git a/docs/pages/client/symfony/index.mdx b/docs/pages/client/symfony/index.mdx
new file mode 100644
index 00000000..30843ffc
--- /dev/null
+++ b/docs/pages/client/symfony/index.mdx
@@ -0,0 +1,88 @@
+# Symfony
+
+Symfony integrates with Traceway via [OpenTelemetry](https://opentelemetry.io/). The PHP OTel extension auto-instruments your Symfony application and exports traces and metrics to Traceway's OTLP endpoints — no manual instrumentation needed.
+
+## Prerequisites
+
+- PHP 8.1+
+- Composer
+- A Traceway project (create one in the dashboard)
+
+## Step 1: Install the PHP OTel Extension
+
+The OpenTelemetry PHP extension provides auto-instrumentation:
+
+```bash
+pecl install opentelemetry
+```
+
+Enable it in your `php.ini`:
+
+```ini
+extension=opentelemetry.so
+```
+
+## Step 2: Install Composer Packages
+
+```bash
+composer require open-telemetry/sdk open-telemetry/exporter-otlp
+```
+
+For automatic Symfony instrumentation, also install:
+
+```bash
+composer require open-telemetry/opentelemetry-auto-symfony
+```
+
+## Step 3: Configure Environment Variables
+
+Add the following to your `.env` file, replacing the endpoint and token with your project values:
+
+```bash
+OTEL_PHP_AUTOLOAD_ENABLED=true
+OTEL_SERVICE_NAME=my-symfony-app
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_ENDPOINT=https://your-traceway-instance.com/api/otel
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer your-project-token
+```
+
+Your Traceway dashboard includes a **Connection** page with a ready-made config snippet and your project token. Go to **Connection** in the sidebar to grab it.
+
+## What Gets Captured
+
+Once configured, the OTel auto-instrumentation captures:
+
+- **Endpoints** — every HTTP request handled by Symfony (method, route, duration)
+- **Status codes** — 2xx, 4xx, 5xx responses
+- **Exceptions** — unhandled errors and exceptions with stack traces
+- **Metrics** — request count, duration histograms
+
+## Test Your Integration
+
+Add a test route to verify data is flowing:
+
+```php
+// src/Controller/TestController.php
+namespace App\Controller;
+
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+class TestController
+{
+ #[Route('/testing', name: 'testing')]
+ public function index(): Response
+ {
+ throw new \RuntimeException("Test error from Traceway integration");
+ }
+}
+```
+
+Visit `/testing` in your browser, then check the Traceway dashboard — the exception should appear within a few seconds.
+
+## Next Steps
+
+- [OpenTelemetry docs](/client/otel) — learn more about how OTel traces and metrics map to Traceway
+- [Connection page](/client/otel#connection-page) — grab your project-specific config from the dashboard
diff --git a/docs/public/symfony.png b/docs/public/symfony.png
new file mode 100644
index 00000000..8152450d
Binary files /dev/null and b/docs/public/symfony.png differ
diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx
index ca756026..34782357 100644
--- a/docs/theme.config.jsx
+++ b/docs/theme.config.jsx
@@ -20,6 +20,7 @@ const SDK_VISIBILITY = {
"js-sdk": "js-",
otel: "otel",
cloudflare: "cloudflare",
+ symfony: "php-symfony",
};
export default {
diff --git a/frontend/src/lib/components/framework-combobox.svelte b/frontend/src/lib/components/framework-combobox.svelte
index 6dedf47a..ebb61f16 100644
--- a/frontend/src/lib/components/framework-combobox.svelte
+++ b/frontend/src/lib/components/framework-combobox.svelte
@@ -34,6 +34,7 @@
{ value: 'nestjs', label: 'NestJS', description: 'Node.js server framework', group: 'JavaScript' },
{ value: 'express', label: 'Express', description: 'Minimal Node.js framework', group: 'JavaScript' },
{ value: 'remix', label: 'Remix', description: 'React full-stack framework', group: 'JavaScript' },
+ { value: 'symfony', label: 'Symfony', description: 'PHP full-stack framework (OTLP)', group: 'PHP' },
{ value: 'cloudflare', label: 'Cloudflare', description: 'Cloudflare Workers (OTLP Traces)', group: 'Backend' },
{ value: 'opentelemetry', label: 'OpenTelemetry', description: 'Vendor-neutral observability', group: 'Backend' },
] as const;
@@ -54,6 +55,7 @@
const goFrameworks = $derived(filteredFrameworks.filter(f => f.group === 'Go'));
const jsFrameworks = $derived(filteredFrameworks.filter(f => f.group === 'JavaScript'));
+ const phpFrameworks = $derived(filteredFrameworks.filter(f => f.group === 'PHP'));
const backendFrameworks = $derived(filteredFrameworks.filter(f => f.group === 'Backend'));
function handleOpenChange(isOpen: boolean) {
@@ -172,6 +174,32 @@
{/each}
</Combobox.Group>
{/if}
+ {#if phpFrameworks.length > 0}
+ <Combobox.Group>
+ <Combobox.GroupHeading class="px-2 py-1.5 text-xs font-semibold text-muted-foreground">PHP</Combobox.GroupHeading>
+ {#each phpFrameworks as fw}
+ <Combobox.Item
+ value={fw.value}
+ class={cn(
+ "data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 ps-2 pe-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4"
+ )}
+ >
+ {#snippet children({ selected })}
+ <div class="flex items-center gap-2">
+ <FrameworkIcon framework={fw.value} />
+ <div class="flex flex-col">
+ <span class="font-medium">{fw.label}</span>
+ <span class="text-xs text-muted-foreground">{fw.description}</span>
+ </div>
+ </div>
+ {#if selected}
+ <Check class="absolute end-2 size-4" />
+ {/if}
+ {/snippet}
+ </Combobox.Item>
+ {/each}
+ </Combobox.Group>
+ {/if}
{#if backendFrameworks.length > 0}
<Combobox.Group>
<Combobox.GroupHeading class="px-2 py-1.5 text-xs font-semibold text-muted-foreground">Backend</Combobox.GroupHeading>
diff --git a/frontend/src/lib/components/framework-icon.svelte b/frontend/src/lib/components/framework-icon.svelte
index df1341d3..88b461bf 100644
--- a/frontend/src/lib/components/framework-icon.svelte
+++ b/frontend/src/lib/components/framework-icon.svelte
@@ -50,6 +50,11 @@
<img src="/cloudflare.png" alt="Cloudflare" class={className} />
{:else if framework === 'opentelemetry'}
<img src="/opentelemetry.png" alt="OpenTelemetry" class={className} />
+{:else if framework === 'symfony'}
+ <svg class={className} viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+ <circle cx="8" cy="8" r="7.5" fill="currentColor" class="text-foreground"/>
+ <path d="M11.5 4.5C11 4 10 3.8 9.2 4.3C8.3 4.9 7.8 5.8 7.3 6.5L7 6.4C6.2 6.1 5.2 6 4.5 6.8C3.9 7.5 4.1 8.4 4.6 8.9L5.3 8.3C5 8 4.9 7.6 5.2 7.3C5.6 6.8 6.4 7 7 7.2L6 9C5.6 9.6 5 10.5 4.3 10.6C3.9 10.7 3.5 10.5 3.3 10.2L2.5 10.6C2.9 11.3 3.6 11.5 4.2 11.4C5.1 11.2 5.8 10.3 6.3 9.5L7.1 8.2L7.8 8.6C8.5 9 8.6 9.7 8.1 10.3L8.8 10.8C9.6 9.8 9.4 8.7 8.5 8.1L7.9 7.7L8 7.5C8.5 6.6 9 5.7 9.6 5.2C10.1 4.8 10.7 4.9 11 5.2L11.5 4.5Z" fill="currentColor" class="text-background"/>
+ </svg>
{:else}
<img src="/custom.png" alt="Custom" class={className} />
{/if}
diff --git a/frontend/src/lib/state/projects.svelte.ts b/frontend/src/lib/state/projects.svelte.ts
index 4f509f2c..7b25001b 100644
--- a/frontend/src/lib/state/projects.svelte.ts
+++ b/frontend/src/lib/state/projects.svelte.ts
@@ -1,7 +1,7 @@
import { api } from '$lib/api';
import { authState } from './auth.svelte';
-export type Framework = 'gin' | 'fiber' | 'chi' | 'fasthttp' | 'stdlib' | 'custom' | 'react' | 'svelte' | 'vuejs' | 'nextjs' | 'nestjs' | 'express' | 'remix' | 'cloudflare' | 'opentelemetry';
+export type Framework = 'gin' | 'fiber' | 'chi' | 'fasthttp' | 'stdlib' | 'custom' | 'react' | 'svelte' | 'vuejs' | 'nextjs' | 'nestjs' | 'express' | 'remix' | 'cloudflare' | 'opentelemetry' | 'symfony';
export const FRONTEND_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs'];
export const JS_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'nextjs', 'nestjs', 'express', 'remix'];
@@ -22,6 +22,7 @@ export const FRAMEWORK_LABELS: Record<Framework, string> = {
remix: 'Remix',
cloudflare: 'Cloudflare',
opentelemetry: 'OpenTelemetry',
+ symfony: 'Symfony',
};
export function getFrameworkLabel(fw: Framework): string {
diff --git a/frontend/src/lib/utils/framework-code.ts b/frontend/src/lib/utils/framework-code.ts
index fddb5070..fedb0da1 100644
--- a/frontend/src/lib/utils/framework-code.ts
+++ b/frontend/src/lib/utils/framework-code.ts
@@ -28,6 +28,8 @@ export function getInstallCommand(framework: Framework): string {
return 'npm install @tracewayapp/express';
case 'remix':
return 'npm install @tracewayapp/remix';
+ case 'symfony':
+ return 'composer require open-telemetry/sdk open-telemetry/exporter-otlp';
case 'cloudflare':
return '';
case 'opentelemetry':
@@ -204,6 +206,16 @@ export default withTraceway({
connectionString: "${connectionString}",
});`;
+ case 'symfony':
+ return `# Add to your .env file
+OTEL_PHP_AUTOLOAD_ENABLED=true
+OTEL_SERVICE_NAME=my-symfony-app
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+OTEL_EXPORTER_OTLP_ENDPOINT=${backendUrl}/api/otel
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${token || 'YOUR_TOKEN'}`;
+
case 'cloudflare':
return '';
@@ -229,6 +241,10 @@ func main() {
}
export function getTestingRouteCode(framework?: Framework): string {
+ if (framework === 'symfony') {
+ return `// In any controller action
+throw new \\RuntimeException("Test error from Traceway integration");`;
+ }
if (framework && isJsFramework(framework)) {
return `// Trigger a test error
throw new Error("Test error from Traceway integration");`;
@@ -239,6 +255,10 @@ throw new Error("Test error from Traceway integration");`;
}
export function getTestingRouteCode2(framework?: Framework): string {
+ if (framework === 'symfony') {
+ return `// In any controller action
+throw new \\RuntimeException("Test error from Traceway integration");`;
+ }
if (framework && isJsFramework(framework)) {
switch (framework) {
case 'react':
@@ -298,11 +318,13 @@ export function getFrameworkLabel(framework: Framework): string {
remix: 'Remix',
cloudflare: 'Cloudflare',
opentelemetry: 'OpenTelemetry',
+ symfony: 'Symfony',
};
return labels[framework] || framework;
}
-export function getCodeLanguage(framework: Framework): 'go' | 'javascript' {
+export function getCodeLanguage(framework: Framework): 'go' | 'javascript' | 'bash' {
+ if (framework === 'symfony') return 'bash';
if (framework === 'opentelemetry') return 'go';
if (framework === 'cloudflare') return 'javascript';
return isJsFramework(framework) ? 'javascript' : 'go';
diff --git a/frontend/src/routes/+page.svelte b/frontend/src/routes/+page.svelte
index 0b79e061..347e3117 100644
--- a/frontend/src/routes/+page.svelte
+++ b/frontend/src/routes/+page.svelte
@@ -124,7 +124,7 @@
projectWithToken ? getCodeLanguage(projectWithToken.framework) : ('go' as const)
);
- const highlightLanguage = $derived(codeLanguage === 'javascript' ? javascript : go);
+ const highlightLanguage = $derived(codeLanguage === 'javascript' ? javascript : codeLanguage === 'bash' ? bash : go);
const testingRouteCode = $derived(getTestingRouteCode(projectWithToken?.framework));
const testingRouteCode2 = $derived(getTestingRouteCode2(projectWithToken?.framework));
diff --git a/frontend/src/routes/connection/+page.svelte b/frontend/src/routes/connection/+page.svelte
index b8277070..cd236a9a 100644
--- a/frontend/src/routes/connection/+page.svelte
+++ b/frontend/src/routes/connection/+page.svelte
@@ -104,9 +104,12 @@ service:
projectWithToken ? getInstallCommand(projectWithToken.framework) : 'go get go.tracewayapp.com'
);
- const highlightLanguage = $derived(
- projectWithToken && isJsFramework(projectWithToken.framework) ? javascript : go
- );
+ const highlightLanguage = $derived.by(() => {
+ if (!projectWithToken) return go;
+ if (projectWithToken.framework === 'symfony') return bash;
+ if (isJsFramework(projectWithToken.framework)) return javascript;
+ return go;
+ });
const isJs = $derived(projectWithToken ? isJsFramework(projectWithToken.framework) : false);
const isReadonly = $derived(
@@ -410,7 +413,7 @@ service:
<CardHeader>
<CardTitle>Installation</CardTitle>
<CardDescription
- >Install the required packages{isJs ? '' : ' using go get'}.</CardDescription
+ >Install the required packages{isJs ? '' : projectWithToken?.framework === 'symfony' ? ' using composer' : ' using go get'}.</CardDescription
>
</CardHeader>
<CardContent>