Download the PHP package stickee/instrumentation without Composer

On this page you can find all versions of the php package stickee/instrumentation. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of stickee/instrumentation

Informations about the package instrumentation

Stickee Instrumentation

This a Composer package for recording metrics. It builds on the OpenTelemetry PHP Instrumentation and OpenTelemetry Laravel auto-instrumentation packages to automatically record performance metrics and provide a simple interface for recording custom metrics.

Quickstart

Requirements

This package requires PHP 8.3 or later and Laravel 11 or later.

The ext-opentelemetry extension and ext-protobuf extension (Windows download) are required.

NB: For those running macOS, you should ensure that your PHP installation is managed by Homebrew (brew install php) as the default PHP installation on macOS is almost always insufficient.

For those using Laravel Herd as a means to manage local PHP installations, you will need to consult the relevant documentation to ensure your local PHP installation (outside of Docker containers) is correctly configured and has access to the required extensions.

Installation

Configuration

The package ships with a default configuration that should be suitable for most use cases except you should add OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE="delta". It is disabled by default; to enable it, set OTEL_PHP_AUTOLOAD_ENABLED="true" in your php.ini or your environment.

:warning: OTEL_PHP_AUTOLOAD_ENABLED="true" (and other OTEL_ variables) will NOT work properly if set in your .env file, as they are used before the .env file is loaded.

Note: You may need to set variables in multiple php.ini files, e.g. /etc/php/8.3/cli/php.ini and /etc/php/8.3/apache2/php.ini to enable it for both CLI (commands, crons and queues) and web requests.

For more advanced configuration, see the OpenTelemetry SDK Configuration.

Variable Description Default
INSTRUMENTATION_RESPONSE_TIME_MIDDLEWARE_ENABLED Enable or disable the response time middleware. true
INSTRUMENTATION_TRACE_SAMPLE_RATE The rate at which to sample traces. 1.0
INSTRUMENTATION_SCRUBBING_REGEXES Comma-separated regular expressions for scrubbing data. null (null uses built-in defaults)
INSTRUMENTATION_SCRUBBING_CONFIG_KEY_REGEXES Comma-separated regular expressions for scrubbing config values. null (null uses built-in defaults)

If you wish to, you can copy the package config to your local config with the publish command, however this is unnecessary in normal usage:

Usage

Installing the package will automatically record many metrics for you. If you wish to track custom metrics, you can use the Instrumentation facade.

Observation Types

There are 4 methods defined in the Stickee\Instrumentation\Exporters\Interfaces\EventsExporterInterface interface.

Event Arguments Description
$exporter->event(string $name, array $attributes = [], float value = 1) $name The event name
$attributes An array of attributes		 Record a single event
$exporter->counter(string $event, array $attributes = [], float $increase = 1) $name The counter name
$attributes An array of attributes
$increase The amount to increase the counter by		 Record an increase in a counter
$exporter->gauge(string $event, array $attributes = [], float $value) $name The gauge name
$attributes An array of attributes
$value The value to record		 Record the current value of a gauge
$exporter->histogram(string $name, ?string $unit, ?string $description, array $buckets, array $attributes = [], float\|int $value) $name The histogram name
$unit The unit of the histogram, e.g. "ms"
$description A description of the histogram
$buckets A set of buckets, e.g. [0.25, 0.5, 1, 5]
$value The value to record
$attributes An array of attributes		 Record the current value of a histogram

Attributes should be an associative array of attribute_name ⇒ attribute_value, e.g.

:warning: Every combination of attributes will be recorded as a separate metric, so be careful not to record too many attributes.

Viewing Metrics Locally

Run the OpenTelemetry stack and view Grafana at http://localhost:3000.

Go to ./vendor/stickee/instrumentation/docker/opentelemetry and run docker compose up -d. This will start Grafana, Loki, Tempo, Prometheus, and the OpenTelemetry Collector and expose them on your local machine.

By default the package will send data to the OpenTelemetry Collector on http://localhost:4318. If you need to change this, set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable. For example if your PHP is running in a docker container you can set OTEL_EXPORTER_OTLP_ENDPOINT="http://host.docker.internal:4318".

Scrubbing Data

By default, data is scrubbed using regexes from INSTRUMENTATION_SCRUBBING_REGEXES and values from the config where the keys match INSTRUMENTATION_SCRUBBING_CONFIG_KEY_REGEXES. To use a custom scrubber, bind your implementation to the Stickee\Instrumentation\DataScrubbers\DataScrubberInterface interface. The package ships with NullDataScrubber to disable scrubbing, CallbackDataScrubber to allow you to register a callback instead of creating a new class, and MultiDataScrubber to bind multiple scrubbers.

Developing

The easiest way to make changes is to make the project you're importing the package in to load the package from your filesystem instead of the Composer repository, like this:

  1. composer remove stickee/instrumentation

  2. Edit composer.json and add

    where "../instrumentation" is the path to where you have this project checked out.

  3. composer require stickee/instrumentation

NOTE: Do not check in your composer.json like this!

Testing

Tests are written using the Pest testing framework and use Orchestra testbench to emulate a Laravel environment. To ensure a wide range of compatibility, these are run via GitHub Actions for a supported matrix of PHP, operating system, and Laravel versions.

You can run tests on your own system by invoking Pest:

OpenTelemetry Collector

The Instrumentation package uses the OpenTelemetry Collector to export metrics. Data is sent from PHP using HTTP + Protobuf to the OpenTelemetry Collector, which is usually running on localhost or as a sidecar in Kubernetes.

Due to PHP's shared-nothing architecture, we need to send Delta temporality metrics to the OpenTelemetry Collector, otherwise every PHP process (and every hit to a website) would need a unique data stream, which would not perform adequately. To get around this, we use Delta temporality and the OpenTelemetry Collector's Aggregation and DeltaToCumulative processors to aggregate metrics in memory before sending them to the exporter. Each collector is given a unique service.instance.id to allow them to be aggregated together later.

The Aggregation processor is written by Stickee and is available in the Stickee OpenTelemetry Collector repository on the feature/aggregation-processor branch.

To update it, run the following commands based off the Custom Collector documentation:

Contributions

Contributions are welcome to all areas of the project, but please provide tests. Code style will be checked using automatically checked via Stickee Canary on your pull request. You can however install it locally using instructions on the above link.

License

Instrumentation is open source software licensed under the MIT license.

All versions of instrumentation with dependencies

PHP Build Version
Package Version
Requires php Version ^8.3
ext-protobuf Version *
open-telemetry/exporter-otlp Version ^1.1
open-telemetry/opentelemetry-auto-laravel Version ^1.0.0
open-telemetry/opentelemetry-auto-psr18 Version ^1.0
open-telemetry/sdk Version ^1.1@beta
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package stickee/instrumentation contains the following files

Loading the files please wait ....