{"id":48811469,"url":"https://github.com/couchbase/couchbase-php-client-opentelemetry","last_synced_at":"2026-04-14T07:34:18.499Z","repository":{"id":348798150,"uuid":"1198866105","full_name":"couchbase/couchbase-php-client-opentelemetry","owner":"couchbase","description":"OpenTelemetry integration for the Couchbase PHP Client","archived":false,"fork":false,"pushed_at":"2026-04-02T23:35:15.000Z","size":45,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T08:52:45.304Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/couchbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T20:47:05.000Z","updated_at":"2026-04-02T23:35:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/couchbase/couchbase-php-client-opentelemetry","commit_stats":null,"previous_names":["couchbase/couchbase-php-client-opentelemetry"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/couchbase/couchbase-php-client-opentelemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fcouchbase-php-client-opentelemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fcouchbase-php-client-opentelemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fcouchbase-php-client-opentelemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fcouchbase-php-client-opentelemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/couchbase","download_url":"https://codeload.github.com/couchbase/couchbase-php-client-opentelemetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/couchbase%2Fcouchbase-php-client-opentelemetry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31787082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-14T07:34:14.242Z","updated_at":"2026-04-14T07:34:18.494Z","avatar_url":"https://github.com/couchbase.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Couchbase PHP Client OpenTelemetry Integration\n\nThis package provides [OpenTelemetry](https://opentelemetry.io/) implementations of the\nCouchbase PHP SDK's observability interfaces (`RequestTracer`, `RequestSpan`, `Meter`,\nand `ValueRecorder`), enabling distributed tracing and metrics export via the OpenTelemetry\necosystem.\n\n## Requirements\n\n- PHP 8.2+\n- `couchbase/couchbase` ^4.5\n- `open-telemetry/api` ^1.0\n\n## Installation\n\n```bash\ncomposer require couchbase/couchbase-opentelemetry\n```\n\n## Usage\n\n### Tracing\n\n```php\n\u003c?php\n\nuse Couchbase\\ClusterOptions;\nuse Couchbase\\Cluster;\nuse Couchbase\\OpenTelemetry\\OpenTelemetryRequestTracer;\n\n// Set up an OpenTelemetry TracerProvider (using the SDK + OTLP exporter as an example)\n$transport = (new \\OpenTelemetry\\Contrib\\Otlp\\OtlpHttpTransportFactory())\n    -\u003ecreate('https://\u003chostname\u003e:\u003cport\u003e/v1/traces', 'application/x-protobuf');\n$exporter   = new \\OpenTelemetry\\Contrib\\Otlp\\SpanExporter($transport);\n$tracerProvider = new \\OpenTelemetry\\SDK\\Trace\\TracerProvider(\n    new \\OpenTelemetry\\SDK\\Trace\\SpanProcessor\\BatchSpanProcessor($exporter)\n);\n\n// Wrap it in the Couchbase tracer\n$tracer = new OpenTelemetryRequestTracer($tracerProvider);\n\n// Pass it to ClusterOptions\n$options = new ClusterOptions();\n$options-\u003ecredentials('Administrator', 'password');\n$options-\u003etracer($tracer);\n\n$cluster = Cluster::connect('couchbase://127.0.0.1', $options);\n```\n\n### Metrics\n\n```php\n\u003c?php\n\nuse Couchbase\\ClusterOptions;\nuse Couchbase\\Cluster;\nuse Couchbase\\OpenTelemetry\\OpenTelemetryMeter;\n\n// Set up an OpenTelemetry MeterProvider (using the SDK + OTLP exporter as an example)\n$transport = (new \\OpenTelemetry\\Contrib\\Otlp\\OtlpHttpTransportFactory())\n    -\u003ecreate('https://\u003chostname\u003e:\u003cport\u003e/v1/metrics', 'application/x-protobuf');\n$exporter = new \\OpenTelemetry\\Contrib\\Otlp\\MetricExporter($transport);\n$meterProvider = \\OpenTelemetry\\SDK\\Metrics\\MeterProvider::builder()\n    -\u003eaddReader(new \\OpenTelemetry\\SDK\\Metrics\\MetricReader\\ExportingReader($exporter))\n    -\u003ebuild();\n\n// Wrap it in the Couchbase meter\n$meter = new OpenTelemetryMeter($meterProvider);\n\n// Pass it to ClusterOptions\n$options = new ClusterOptions();\n$options-\u003ecredentials('Administrator', 'password');\n$options-\u003emeter($meter);\n\n$cluster = Cluster::connect('couchbase://127.0.0.1', $options);\n```\n\n### Tracing and Metrics together\n\n```php\n\u003c?php\n\nuse Couchbase\\ClusterOptions;\nuse Couchbase\\Cluster;\nuse Couchbase\\OpenTelemetry\\OpenTelemetryRequestTracer;\nuse Couchbase\\OpenTelemetry\\OpenTelemetryMeter;\n\n// ... set up $tracerProvider and $meterProvider as shown above ...\n\n$tracer = new OpenTelemetryRequestTracer($tracerProvider);\n$meter  = new OpenTelemetryMeter($meterProvider);\n\n$options = new ClusterOptions();\n$options-\u003ecredentials('Administrator', 'password');\n$options-\u003etracer($tracer);\n$options-\u003emeter($meter);\n\n$cluster = Cluster::connect('couchbase://127.0.0.1', $options);\n```\n\n## Classes\n\n| Class | Couchbase Interface | Description |\n|---|---|---|\n| `OpenTelemetryRequestTracer` | `RequestTracer` | Creates OTel CLIENT spans for each SDK operation |\n| `OpenTelemetryRequestSpan` | `RequestSpan` | Wraps an OTel `SpanInterface`; maps Couchbase status codes |\n| `OpenTelemetryMeter` | `Meter` | Creates and caches OTel histograms for SDK metrics |\n| `OpenTelemetryValueRecorder` | `ValueRecorder` | Records values against an OTel histogram, converting units |\n\n## Unit Conversion\n\nThe Couchbase SDK reports operation durations internally in **microseconds**.\n`OpenTelemetryValueRecorder` automatically converts values to **seconds** when the\nmetric's unit tag is `\"s\"` (as used for `db.client.operation.duration`), matching the\nOpenTelemetry semantic conventions for duration metrics.\n\n## Instrumentation Scope\n\nBoth the tracer and meter register under the instrumentation scope name\n`com.couchbase.client/php`.\n\n## Development\n\n### Running Tests\n\nThis library includes integration tests that verify the OpenTelemetry instrumentation works correctly with the Couchbase PHP SDK.\n\n#### Prerequisites\n\n1. **Install dependencies**:\n   ```bash\n   composer install\n   ```\n\n2. **Couchbase Server**: Tests require a running Couchbase Server instance. You can use:\n   - Local installation\n   - Docker: `docker run -d --name couchbase -p 8091-8096:8091-8096 -p 11210-11211:11210-11211 couchbase:latest`\n   - Couchbase Cloud\n\n3. **Environment Configuration** (optional):\n   ```bash\n   export TEST_CONNECTION_STRING=\"couchbase://127.0.0.1\"\n   export TEST_BUCKET=\"default\"\n   export TEST_USERNAME=\"Administrator\"\n   export TEST_PASSWORD=\"password\"\n   export TEST_SERVER_VERSION=\"8.0.0\"\n   ```\n\n   **Note**: For multi-node clusters, the connection string can include multiple hosts (e.g., `couchbase://host1,host2,host3`). The tests will use the first host for administrative API calls.\n\n#### Running Tests\n\n```bash\n# Run all tests\ncomposer test\n# or\nvendor/bin/phpunit\n\n# Run only integration tests (recommended)\ncomposer test:integration\n# or\nvendor/bin/phpunit --testsuite=integration\n\n# Run only unit tests\ncomposer test:unit\n# or\nvendor/bin/phpunit --testsuite=unit\n\n# Run with code coverage (requires Xdebug)\ncomposer test:coverage\n# or\nvendor/bin/phpunit --coverage-html coverage/\n\n# Run integration tests with coverage\ncomposer test:integration:coverage\n\n# Check PHP syntax\ncomposer lint\n```\n\n### Code Quality\n\nThis project uses automated code quality tools to maintain consistent code style and catch syntax errors. These same checks run in CI, so running them locally helps ensure your contributions pass all quality gates.\n\n#### Available Commands\n\n```bash\n# Check PHP syntax for all source files\ncomposer lint\n\n# Check code style without making changes (dry-run)\ncomposer cs-check\n\n# Automatically fix code style issues\ncomposer cs-fix\n\n# Run all quality checks (syntax + style)\ncomposer quality\n```\n\n#### Code Style Configuration\n\nThe project uses [PHP CS Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer) to maintain consistent code formatting. The tool will automatically format your code according to project standards.\n\n**Recommended workflow:**\n1. Write your code\n2. Run `composer quality` to check for issues\n3. Run `composer cs-fix` to automatically fix style issues\n4. Commit your changes\n\nThe `composer quality` command runs the same checks as our CI pipeline, so passing it locally means your PR should pass the automated quality checks.\n\n#### Test Structure\n\n- **Integration Tests** (`tests/Integration/`): Test the full OpenTelemetry integration with real Couchbase operations\n- **Unit Tests** (`tests/` excluding Integration): Currently empty, future unit tests will go here\n\nThe integration tests verify:\n- Distributed tracing functionality with proper span creation and context propagation\n- Metrics collection and export\n- OpenTelemetry semantic conventions compliance\n- Error handling and span status mapping\n\n#### Continuous Integration\n\nTests run automatically on GitHub Actions for:\n- PHP 8.2, 8.3, 8.4\n- Multiple Couchbase Server versions\n- Linux environment\n\nSee `.github/workflows/tests.yml` for the complete CI configuration.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n    Copyright 2026-Present Couchbase, Inc.\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n        http://www.apache.org/licenses/LICENSE-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase%2Fcouchbase-php-client-opentelemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcouchbase%2Fcouchbase-php-client-opentelemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcouchbase%2Fcouchbase-php-client-opentelemetry/lists"}