summaryrefslogtreecommitdiff
path: root/vendor/open-telemetry/context/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/open-telemetry/context/README.md')
-rw-r--r--vendor/open-telemetry/context/README.md63
1 files changed, 63 insertions, 0 deletions
diff --git a/vendor/open-telemetry/context/README.md b/vendor/open-telemetry/context/README.md
new file mode 100644
index 000000000..4dfe0e23f
--- /dev/null
+++ b/vendor/open-telemetry/context/README.md
@@ -0,0 +1,63 @@
+[![Releases](https://img.shields.io/badge/releases-purple)](https://github.com/opentelemetry-php/context/releases)
+[![Source](https://img.shields.io/badge/source-context-green)](https://github.com/open-telemetry/opentelemetry-php/tree/main/src/Context)
+[![Mirror](https://img.shields.io/badge/mirror-opentelemetry--php:context-blue)](https://github.com/opentelemetry-php/context)
+[![Latest Version](http://poser.pugx.org/open-telemetry/context/v/unstable)](https://packagist.org/packages/open-telemetry/context/)
+[![Stable](http://poser.pugx.org/open-telemetry/context/v/stable)](https://packagist.org/packages/open-telemetry/context/)
+
+# OpenTelemetry Context
+
+Immutable execution scoped propagation mechanism, for further details see [opentelemetry-specification][1].
+
+## Installation
+
+```shell
+composer require open-telemetry/context
+```
+
+## Usage
+
+### Implicit propagation
+
+```php
+$context = Context::getCurrent();
+// modify context
+$scope = $context->activate();
+try {
+ // run within new context
+} finally {
+ $scope->detach();
+}
+```
+
+It is recommended to use a `try-finally` statement after `::activate()` to ensure that the created scope is properly `::detach()`ed.
+
+## Async applications
+
+### Fiber support
+
+Requires `PHP >= 8.1`, an NTS build, `ext-ffi`, and setting the environment variable `OTEL_PHP_FIBERS_ENABLED` to a truthy value. Additionally `vendor/autoload.php` has to be preloaded for non-CLI SAPIs if [`ffi.enable`](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.enable) is set to `preload`.
+
+### Event loops
+
+Event loops have to restore the original context on callback execution. A basic implementation could look like the following, though implementations should avoid keeping unnecessary references to arguments if possible:
+
+```php
+function bindContext(Closure $closure): Closure {
+ $context = Context::getCurrent();
+ return static function (mixed ...$args) use ($closure, $context): mixed {
+ $scope = $context->activate();
+ try {
+ return $closure(...$args);
+ } finally {
+ $scope->detach();
+ }
+ };
+}
+```
+
+## Contributing
+
+This repository is a read-only git subtree split.
+To contribute, please see the main [OpenTelemetry PHP monorepo](https://github.com/open-telemetry/opentelemetry-php).
+
+[1]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/context/README.md#context