cc @getsentry/support

Summary

The sentry-php-sdk skill is missing documentation for significant features added in SDK versions 4.23.0–4.28.0 (released between March and June 2026). The highest-impact gap is the OpenTelemetry integration (OTLPIntegration + SentryPropagator), which enables bidirectional interoperability with OpenTelemetry traces. This needs architectural guidance on documentation structure.

Missing OpenTelemetry Features (High Priority)

1. OTLPIntegration (v4.23.0, PR #2030)

What it does: Allows Sentry PHP SDK to interoperate with OpenTelemetry traces instead of native Sentry tracing.

Example from CHANGELOG:

\Sentry\init([
    'dsn' => '__YOUR_DSN__',
    'integrations' => [
        new \Sentry\Integration\OTLPIntegration(),
    ],
]);

Note: This integration is mutually exclusive with Sentry native tracing—the SDK disables it if traces_sample_rate or traces_sampler are set.

Documentation decision needed:

• Should this go in references/tracing.md as a section, or a new references/opentelemetry.md?
• Do we need to explain when to choose OTel over native tracing?
• What's the recommended setup for users already using OpenTelemetry PHP?

2. SentryPropagator (v4.28.0, PR #2105)

What it does: OpenTelemetry TextMapPropagator that injects/extracts sentry-trace headers in OTel contexts, enabling distributed tracing between Sentry-instrumented and OTel-instrumented services.

Where to document: Likely in the same place as OTLPIntegration above, with usage examples.

Missing Config Options (Medium Priority)

These are mechanical additions to the config reference tables:

3. profiles_sampler (v4.27.0, PR #2082)

What it does: Dynamic per-transaction profiling decision (similar to traces_sampler).

Where to add:

• SKILL.md config table (line ~240–265)
• references/profiling.md or references/tracing.md

Analogous to traces_sampler — should have similar documentation structure.

4. log_flush_threshold (v4.23.0, PR #2032)

What it does: Automatically flush buffered logs after N records (useful for CLI scripts).

Example from CHANGELOG:

\Sentry\init([
    'dsn' => '__YOUR_DSN__',
    'enable_logs' => true,
    'log_flush_threshold' => 20,
]);

Where to add:

• SKILL.md config table
• references/logging.md (similar to metric_flush_threshold which is already documented in metrics.md)

Missing Monolog Handlers (Medium Priority)

The skill documents generic Monolog integration via LogsHandler, but two new specialized handlers are missing:

5. ExceptionToSentryIssueHandler (v4.25.0, PR #2061)

What it does: Captures only exceptions as Sentry issues, without converting log messages to errors.

Use case: Users who want exception-only Sentry issues but still send logs elsewhere (e.g., to Datadog or CloudWatch).

6. LogToSentryIssueHandler (v4.26.0, PR #2075)

What it does: Captures log messages as Sentry issues (not structured logs).

Use case: Users who want critical logs to appear as issues in Sentry's issue stream for alerting.

Where to add: references/logging.md — add a new section "Specialized Monolog Handlers" with examples for both.

Deprecation Warning (Low Priority)

7. Sentry\Monolog\Handler deprecated (v4.24.0, PR #2051)

The old handler is deprecated in favor of LogsHandler with enable_logs: true. The skill doesn't mention this deprecation—consider adding a note in references/logging.md to steer users toward the modern API.

Agent Transport (Low Priority)

8. AgentClient and AgentClientBuilder (v4.26.0, PR #2062, #2072)

What it does: Hands off envelope delivery to a local Sentry agent process instead of direct HTTP. Falls back to HTTP if the agent is unavailable.

Use case: High-throughput or latency-sensitive applications that offload SDK delivery overhead to a sidecar process.

Documentation decision needed: This is an advanced transport option—should it be in SKILL.md or a separate references/agent-transport.md?

Reviewed PRs

All recent SDK changes reviewed; highest-impact items listed above. Other PRs were CI tooling, dependency bumps, or bug fixes with no public API surface changes.