o

Merge branch 'main' into 84-implicit-null
brettmc · Oct 2, 2024 · 01e7c24 · 01e7c24
2 parents d51fce8 + fd24607
commit 01e7c24
Show file tree

Hide file tree

Showing 39 changed files with 525 additions and 235 deletions.
diff --git a/.gitignore b/.gitignore
@@ -30,3 +30,9 @@ tests/TraceContext/W3CTestService/trace-context
 
 # deptrac cache
 /.deptrac.cache
+
+# output from phpdoc 
+docs/build
+
+# cache from phpdoc
+.phpdoc
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -236,3 +236,21 @@ make phpmetrics
 
 This will generate a HTML PhpMetrics report in the `var/metrics` directory. Make sure to run `make test` before to
 create the test log-file, used by the metrics report.
+
+## API Documentation
+
+We use [phpDocumentor](https://phpdoc.org/) to automatically generate API documentation from DocBlocks in the code.
+
+To generate a recent version of the API documentation, you can run:
+
+```bash
+make phpdoc
+```
+
+To preview the documentation and changes you might expect, you can run:
+
+```bash
+make phpdoc-preview
+```
+
+This will start a HTTP server running at <http://localhost:8080> serving the updated documentation files.
diff --git a/Makefile b/Makefile
@@ -41,6 +41,10 @@ psalm: ## Run psalm
 	$(DC_RUN_PHP) env XDEBUG_MODE=off vendor-bin/psalm/vendor/bin/psalm --threads=1 --no-cache
 psalm-info: ## Run psalm and show info
 	$(DC_RUN_PHP) env XDEBUG_MODE=off vendor-bin/psalm/vendor/bin/psalm --show-info=true --threads=1
+phpdoc: ## Run phpdoc
+	$(DOCKER_COMPOSE) -f docker-compose.phpDocumentor.yaml run --rm phpdoc
+phpdoc-preview:
+	$(DOCKER_COMPOSE) -f docker-compose.phpDocumentor.yaml run --service-ports --rm preview
 phpstan: ## Run phpstan
 	$(DC_RUN_PHP) env XDEBUG_MODE=off vendor/bin/phpstan analyse --memory-limit=256M
 infection: ## Run infection (mutation testing)

diff --git a/README.md b/README.md
@@ -14,14 +14,14 @@ Please read the official documentation: https://opentelemetry.io/docs/instrument
 
 | Package              | Latest                                                                                                                                                                                                                                                                                                                                                  |
 |----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| API                  | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/api/v/stable)](https://packagist.org/packages/open-telemetry/api/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/api/v/unstable)](https://packagist.org/packages/open-telemetry/api/)                                                                                 |
-| SDK                  | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/sdk/v/stable)](https://packagist.org/packages/open-telemetry/sdk/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/sdk/v/unstable)](https://packagist.org/packages/open-telemetry/sdk/)                                                                                 |
-| Context              | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/context/v/stable)](https://packagist.org/packages/open-telemetry/context/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/context/v/unstable)](https://packagist.org/packages/open-telemetry/context/)                                                                 |
-| Semantic Conventions | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/sem-conv/v/stable)](https://packagist.org/packages/open-telemetry/sem-conv/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/sem-conv/v/unstable)](https://packagist.org/packages/open-telemetry/sem-conv/)                                                             |
-| OTLP Exporter        | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/exporter-otlp/v/stable)](https://packagist.org/packages/open-telemetry/exporter-otlp/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/exporter-otlp/v/unstable)](https://packagist.org/packages/open-telemetry/exporter-otlp/)                                         |
-| gRPC Transport       | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/transport-grpc/v/stable)](https://packagist.org/packages/open-telemetry/transport-grpc/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/transport-grpc/v/unstable)](https://packagist.org/packages/open-telemetry/transport-grpc/)                                     |
-| OTLP Protobuf Files  | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/gen-otlp-protobuf/v/stable)](https://packagist.org/packages/open-telemetry/gen-otlp-protobuf/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/gen-otlp-protobuf/v/unstable)](https://packagist.org/packages/open-telemetry/gen-otlp-protobuf/)                         |
-| B3 Propagator        | [![Latest Stable Version](http://poser.pugx.org/open-telemetry/extension-propagator-b3/v/stable)](https://packagist.org/packages/open-telemetry/extension-propagator-b3/) [![Latest Unstable Version](http://poser.pugx.org/open-telemetry/extension-propagator-b3/v/unstable)](https://packagist.org/packages/open-telemetry/extension-propagator-b3/) |
+| API                  | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/api/v/stable)](https://packagist.org/packages/open-telemetry/api/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/api/v/unstable)](https://packagist.org/packages/open-telemetry/api/)                                                                                 |
+| SDK                  | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/sdk/v/stable)](https://packagist.org/packages/open-telemetry/sdk/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/sdk/v/unstable)](https://packagist.org/packages/open-telemetry/sdk/)                                                                                 |
+| Context              | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/context/v/stable)](https://packagist.org/packages/open-telemetry/context/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/context/v/unstable)](https://packagist.org/packages/open-telemetry/context/)                                                                 |
+| Semantic Conventions | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/sem-conv/v/stable)](https://packagist.org/packages/open-telemetry/sem-conv/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/sem-conv/v/unstable)](https://packagist.org/packages/open-telemetry/sem-conv/)                                                             |
+| OTLP Exporter        | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/exporter-otlp/v/stable)](https://packagist.org/packages/open-telemetry/exporter-otlp/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/exporter-otlp/v/unstable)](https://packagist.org/packages/open-telemetry/exporter-otlp/)                                         |
+| gRPC Transport       | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/transport-grpc/v/stable)](https://packagist.org/packages/open-telemetry/transport-grpc/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/transport-grpc/v/unstable)](https://packagist.org/packages/open-telemetry/transport-grpc/)                                     |
+| OTLP Protobuf Files  | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/gen-otlp-protobuf/v/stable)](https://packagist.org/packages/open-telemetry/gen-otlp-protobuf/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/gen-otlp-protobuf/v/unstable)](https://packagist.org/packages/open-telemetry/gen-otlp-protobuf/)                         |
+| B3 Propagator        | [![Latest Stable Version](https://poser.pugx.org/open-telemetry/extension-propagator-b3/v/stable)](https://packagist.org/packages/open-telemetry/extension-propagator-b3/) [![Latest Unstable Version](https://poser.pugx.org/open-telemetry/extension-propagator-b3/v/unstable)](https://packagist.org/packages/open-telemetry/extension-propagator-b3/) |
 
 Releases for both this repository and [contrib](https://github.com/open-telemetry/opentelemetry-php-contrib) are
 based on read-only [git subtree splits](https://github.com/splitsh/lite) from our monorepo. You should refer to
@@ -32,6 +32,8 @@ You can also look at the read-only repositories, which live in the
 
 ## Contributing
 
+[![GitHub repo Good Issues for newbies](https://img.shields.io/github/issues/open-telemetry/opentelemetry-php/good%20first%20issue?style=flat&logo=github&logoColor=green&label=Good%20First%20issues)](https://github.com/open-telemetry/opentelemetry-php/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) [![GitHub Help Wanted issues](https://img.shields.io/github/issues/open-telemetry/opentelemetry-php/help%20wanted?style=flat&logo=github&logoColor=b545d1&label=%22Help%20Wanted%22%20issues)](https://github.com/open-telemetry/opentelemetry-php/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) [![GitHub Help Wanted PRs](https://img.shields.io/github/issues-pr/open-telemetry/opentelemetry-php/help%20wanted?style=flat&logo=github&logoColor=b545d1&label=%22Help%20Wanted%22%20PRs)](https://github.com/open-telemetry/opentelemetry-php/pulls?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) [![GitHub repo Issues](https://img.shields.io/github/issues/open-telemetry/opentelemetry-php?style=flat&logo=github&logoColor=red&label=Issues)](https://github.com/open-telemetry/opentelemetry-php/issues?q=is%3Aopen)
+
 We would love to have you on board, please see our [Development README](./DEVELOPMENT.md) and [Contributing README](./CONTRIBUTING.md).
 
 ## Specification conformance

diff --git a/composer.json b/composer.json
@@ -20,7 +20,7 @@
         "symfony/config": "^5.4 || ^6.4 || ^7.0",
         "symfony/polyfill-mbstring": "^1.23",
         "symfony/polyfill-php82": "^1.26",
-        "tbachert/spi": ">= 0.2.1"
+        "tbachert/spi": "^1.0.1"
     },
     "config": {
         "sort-packages": true,

diff --git a/docker-compose.phpDocumentor.yaml b/docker-compose.phpDocumentor.yaml
@@ -0,0 +1,11 @@
+services:
+  phpdoc:
+    image: phpdoc/phpdoc:3
+    volumes:
+      - ./:/data
+  preview:
+    image: nginx:alpine
+    ports:
+      - 8080:80
+    volumes:
+      - ./docs/build:/usr/share/nginx/html
diff --git a/examples/traces/demo/collector/config.yaml b/examples/traces/demo/collector/config.yaml
@@ -4,8 +4,8 @@ receivers:
       grpc:
 
 exporters:
-  logging:
-    logLevel: debug
+  debug:
+    verbosity: detailed
   zipkin:
     endpoint: "http://zipkin:9411/api/v2/spans"
   jaeger:
@@ -19,6 +19,6 @@ service:
       receivers:
         - otlp
       exporters:
-        - logging
+        - debug
         - zipkin
         - jaeger
diff --git a/examples/traces/demo/docker-compose.yml b/examples/traces/demo/docker-compose.yml
@@ -41,7 +41,7 @@ services:
       OTEL_SERVICE_NAME: service-three
 
   collector:
-    image: otel/opentelemetry-collector-contrib:0.39.0
+    image: otel/opentelemetry-collector-contrib
     volumes:
       - './collector:/etc/otel'
     ports:

diff --git a/files/collector/otel-collector-config.yml b/files/collector/otel-collector-config.yml
@@ -8,7 +8,7 @@ receivers:
 exporters:
   zipkin:
     endpoint: "http://zipkin:9411/api/v2/spans"
-  logging:
+  debug:
     verbosity: detailed
 
 processors:
@@ -27,12 +27,12 @@ service:
   pipelines:
     traces:
       receivers: [otlp, zipkin]
-      exporters: [logging]
+      exporters: [debug]
       processors: [batch]
     metrics:
       receivers: [otlp]
-      exporters: [logging]
+      exporters: [debug]
     logs:
       receivers: [ otlp ]
       processors: [ batch ]
-      exporters: [ logging ]
+      exporters: [ debug ]
diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdocumentor
+        configVersion="3"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://www.phpdoc.org"
+>
+    <title>OpenTelemetry PHP</title>
+    <paths>
+        <output>docs/build</output>
+    </paths>
+</phpdocumentor>
diff --git a/src/API/Instrumentation/WithSpanHandler.php b/src/API/Instrumentation/WithSpanHandler.php
@@ -18,7 +18,7 @@ class WithSpanHandler
     /**
      * @psalm-suppress ArgumentTypeCoercion
      */
-    public static function pre(mixed $target, array $params, string $class, string $function, ?string $filename, ?int $lineno, ?array $span_args = [], ?array $attributes = []): void
+    public static function pre(mixed $target, array $params, ?string $class, string $function, ?string $filename, ?int $lineno, ?array $span_args = [], ?array $attributes = []): void
     {
         static $instrumentation;
         $instrumentation ??= new CachedInstrumentation(name: 'io.opentelemetry.php.with-span', schemaUrl: 'https://opentelemetry.io/schemas/1.25.0');

diff --git a/src/API/Metrics/LateBindingMeter.php b/src/API/Metrics/LateBindingMeter.php
@@ -58,9 +58,4 @@ public function createObservableUpDownCounter(string $name, ?string $unit = null
     {
         return ($this->meter ??= ($this->factory)())->createObservableUpDownCounter($name, $unit, $description, $advisory, $callbacks);
     }
-
-    public function isEnabled(): bool
-    {
-        return true;
-    }
 }
diff --git a/src/API/Metrics/MeterInterface.php b/src/API/Metrics/MeterInterface.php
@@ -178,6 +178,4 @@ public function createObservableUpDownCounter(
         array|callable $advisory = [],
         callable ...$callbacks,
     ): ObservableUpDownCounterInterface;
-
-    public function isEnabled(): bool;
 }
diff --git a/src/API/Metrics/Noop/NoopMeter.php b/src/API/Metrics/Noop/NoopMeter.php
@@ -56,9 +56,4 @@ public function createObservableUpDownCounter(string $name, ?string $unit = null
     {
         return new NoopObservableUpDownCounter();
     }
-
-    public function isEnabled(): bool
-    {
-        return false;
-    }
 }
diff --git a/src/Config/SDK/composer.json b/src/Config/SDK/composer.json
@@ -21,7 +21,7 @@
         "open-telemetry/context": "^1.0",
         "open-telemetry/sdk": "^1.0",
         "symfony/config": "^5.4 || ^6.4 || ^7.0",
-        "tbachert/spi": ">= 0.2.1"
+        "tbachert/spi": "^1.0.1"
     },
     "autoload": {
         "psr-4": {

diff --git a/src/SDK/Metrics/Instrument.php b/src/SDK/Metrics/Instrument.php
@@ -4,8 +4,6 @@
 
 namespace OpenTelemetry\SDK\Metrics;
 
-use OpenTelemetry\API\Metrics\MeterInterface;
-
 final class Instrument
 {
     public function __construct(
@@ -14,12 +12,6 @@ public function __construct(
         public readonly ?string $unit,
         public readonly ?string $description,
         public readonly array $advisory = [],
-        public readonly ?MeterInterface $meter = null,
     ) {
     }
-
-    public function isEnabled(): bool
-    {
-        return $this->meter?->isEnabled() ?? true;
-    }
 }