Download the PHP package jaigateway/monitor without Composer

On this page you can find all versions of the php package jaigateway/monitor. 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?

Informations about the package monitor

jaigateway/monitor (PHP and Laravel)

Error reporting for PHP 8.0+ and Laravel 10, 11 and 12. No third-party runtime dependencies (uses the curl extension, with a streams fallback). Speaks the JaiGateway Monitor ingest protocol v1 (POST {host}/api/ingest/events/).

Install

Plain PHP in 5 lines

Events are queued and sent once, in one POST, at the end of the request (after fastcgi_finish_request() when available, so the user's response is never delayed).

Laravel

The package is auto-discovered. Add to .env:

Then hook the exception handler.

Laravel 11 / 12, bootstrap/app.php:

Laravel 10, app/Exceptions/Handler.php:

Verify the setup: php artisan insight:test sends a test exception and prints the HTTP status. Publish the config with php artisan vendor:publish --tag=insight-config.

Laravel's $dontReport / dontReport() is respected. Log messages and SQL queries (truncated, no bindings) become breadcrumbs. The authenticated user is attached only when INSIGHT_SEND_PII=true.

Anywhere in your code (no facade needed): \Insight\Insight::captureException($e), \Insight\Insight::captureMessage('x', 'warning'), \Insight\Insight::setTag('feature', 'checkout').

API

Call Notes
Insight::init(array $options): Client Creates the global client.
Insight::captureException(Throwable, array $context = []) Context: tags, extra, user, level, fingerprint, request. Returns whether it was queued.
Insight::captureMessage(string, string $level = 'info')
Insight::setUser(?array), setTag, setTags, setExtra Scope data attached to later events.
Insight::addBreadcrumb(string $message, string $category = 'custom', string $level = 'info', array $data = [])
Insight::flush(): ?int Sends now, returns the HTTP status or null.
Insight::registerErrorHandlers() Chains to existing handlers; records the request transaction at shutdown when performance is on.
Insight::recordTransaction(string $name, float $durationMs, ?int $status = null, bool $error = false, string $op = 'http.server') See Performance monitoring.
Insight::startTransaction(), setTransactionName(string), finishTransaction(?string $name = null, ?int $status = null) Plain PHP request timing.

The same methods exist on Insight\Client (new Client($options, ?Transport $transport)).

Options

Option Default Laravel env
api_key none (SDK disabled without it) INSIGHT_API_KEY
host (or endpoint) none. /api/ingest/events/ is appended; trailing slashes and a host already ending in /api are fine INSIGHT_HOST
release, environment, server_name null, null, hostname INSIGHT_RELEASE, INSIGHT_ENVIRONMENT
sample_rate 1.0 INSIGHT_SAMPLE_RATE
before_send null. callable(array $event): array\|null, return null to drop
send_default_pii false INSIGHT_SEND_PII
max_breadcrumbs 100
connect_timeout / timeout 2 / 3 seconds
debug false. Logs problems with error_log INSIGHT_DEBUG
rate_limit_per_minute 60 per key, shared via APCu or a temp file
max_events_per_request 20 (also the batch size)
performance false (plain PHP), true under Laravel INSIGHT_PERFORMANCE
performance_ignore health checks, static paths (see below) INSIGHT_PERFORMANCE_IGNORE
performance_window_seconds 60
performance_spans true Collect spans (queries, HTTP calls, custom). Laravel env INSIGHT_PERFORMANCE_SPANS.
performance_cache_spans true Cache spans (Redis commands, hit/miss markers). Needs performance_spans. Laravel env INSIGHT_PERFORMANCE_CACHE_SPANS.
trace_propagation_targets [] (never add traceparent to outgoing calls) INSIGHT_TRACE_PROPAGATION_TARGETS (comma list). See "Distributed tracing".

How failures and quota are handled

The SDK never throws into your app and never retries more than once (PHP must not block).

Response Behaviour
201 done
400 dropped
401, 403 invalid key or no write permission: SDK disabled for the rest of the process, logged once when debug is on
413 batch is split in halves and resent; a single oversized event is dropped
429 rate_limited / quota_exceeded events dropped; sending is paused until Retry-After (default 60 s, capped at 1 h). The pause is stored in APCu or a small file in the temp dir keyed by a hash of the API key, so other requests skip sending too
5xx, network error one quick retry, then dropped

Use php artisan insight:test or Insight::flush() (returns the status) to see the outcome. Set debug to get error_log lines.

Performance monitoring

Reports how long each route takes: request count, errors, min/avg/max and p50/p95/p99 per transaction, plus a few slow or failed samples. It has its own monthly quota ("tracked requests"), separate from error events.

What is measured. One transaction per HTTP request, named METHOD route-template (GET /items/{id}, GET / for the root), never the raw URL. A request that matched no route is GET <unmatched>. Queue jobs are TASK App\Jobs\SendMail (op queue.task). Duration is from LARAVEL_START (when set; not under Octane) to the moment the response is ready.

Errors vs 4xx. A transaction counts as an error when the response status is 5xx, or an exception was reported (Laravel: through Integration) or uncaught (plain PHP). 4xx responses (404, 422, 401 ...) are NOT errors. Queue: every attempt is one transaction; an attempt that threw is an error even when the job will be retried (attempt-level error rate); JobFailed only records when that attempt did not already record the exception.

Turn it on / off.

Ignored paths. Default: /health, /healthz, /ping, /status, /metrics, /favicon.ico, /robots.txt, /ready, /live, /up, /storage/, /build/, /assets/ (a prefix matches on a path boundary: /up ignores /up/x but not /users). Override with performance_ignore (array or comma list, INSIGHT_PERFORMANCE_IGNORE=/internal/,#^/v\d+/ping$#); entries starting with # or ~ are regular expressions. A custom list replaces the defaults.

How the once-a-minute window works in PHP-FPM. Every request is a fresh process with no background thread, so nothing can be aggregated in memory. Each request instead adds its duration to a small shared record (APCu when enabled, else a JSON file insight_<hash>_m.json in sys_get_temp_dir() guarded by flock, else process memory for CLI/Octane/queue workers) bucketed by minute. The first request that sees the stored minute has elapsed closes it, hands it to itself atomically (under the lock, so exactly one request per window) and POSTs it once after the response (fastcgi_finish_request()). That is about one HTTP call per minute per app regardless of traffic, and the cost per request is one lock, one small read and one write (no network). Consequences: the last minute of traffic is sent when the next request arrives after it; a low-traffic app reports with that delay; state is shared per API key and per server (not across machines: each server sends its own summary).

Failures and quota. Never throws, never blocks the response.

Response Behaviour
201 done
400 window dropped
401, 403 metrics switched off (stored in the shared state, other workers skip too), logged once with debug on; error reporting is unaffected
413 resent without samples (counts kept)
429 rate_limited window kept, retried by a later request after Retry-After
429 quota_exceeded (quota: "performance") metrics paused until Retry-After (capped at 1 h) for all workers, data dropped meanwhile. Error reporting continues normally
5xx, network error window kept, retried by a later request after 30 s; at most 5 windows are buffered (oldest dropped)

Option performance_window_seconds (default 60) changes the window length. Without APCu or a writable temp dir (state mode none) windows live in process memory only.

Spans and traces (where the time goes)

With performance on, the SDK also records spans: timed steps inside a request or job. JaiGateway Monitor shows the slowest queries and external services, a "where the time goes" breakdown per endpoint, and a trace view that links a failed request to its errors.

What is collected: database queries (op db.query), outbound HTTP calls (http.client), your own spans, and per request a random trace_id. Error events captured during the request carry the same trace_id.

Privacy guarantees:

Laravel: queries, HTTP client calls (Http:: facade) and queue jobs are instrumented automatically. Config performance_spans / env INSIGHT_PERFORMANCE_SPANS=false turns it off (it only runs when performance is on).

Cache spans

Laravel (on by default with spans; performance_cache_spans / INSIGHT_PERFORMANCE_CACHE_SPANS=false turns them off):

Custom spans:

Spans outside a request (CLI scripts) are aggregated under an empty transaction name and appear in summaries only.

Plain PHP / other frameworks:

Call Insight::startTransaction() at the start of the request so spans get offsets from the request start and errors get a trace_id.

Distributed tracing

JaiGateway Monitor uses the W3C traceparent header (00-<32 hex trace id>-<16 hex parent span id>-<01|00>), so a browser page, this PHP app and the services it calls can show up as one waterfall in the dashboard. Needs performance on (the default in Laravel).

Incoming (automatic). Every request reads traceparent (plain PHP: $_SERVER['HTTP_TRACEPARENT']; Laravel: the request header, also under Octane). A valid header (version 00, ids not all zeros, any letter case) makes the request join that trace: its trace_id is the header's, it gets its own new 16-hex span_id and remembers parent_span_id. Error events captured during the request carry the same trace_id. A missing or malformed header just starts a new trace. Samples are sent with kind: "server", op: "http.server" (or "queue.task"), span_id and parent_span_id.

If the header's flags say sampled (01), the request is always kept as a sample, however fast and successful, so both halves of the trace exist. Up to 20 such forced samples are kept per one-minute window, in addition to the usual slowest 3, failed 5 and 1 random one. (The server reads 10 samples per request body, so the SDK sends forced samples beyond that in extra, samples-only bodies.) When a payload is too big or the server answers 413, ordinary samples go first, then span lists, and forced samples are the last to be dropped.

For work that is not an HTTP request (a queue job whose payload carries the parent's header, a CLI command):

Outgoing (opt-in). Nothing is added unless you list the hosts that may receive the header:

Laravel: config/insight.php trace_propagation_targets, or INSIGHT_TRACE_PROPAGATION_TARGETS=api.example.com,*.example.com (plain host entries only in the env list; commas cannot appear in a regex). Entries are matched against host[:port], case-insensitively: a host without port matches any port, * matches one or more characters of a host name, #...# is a regular expression. A matching call, made while a trace is active, gets traceparent: 00-<trace id>-<span id of the http.client span recorded for that call>-<01|00> (the flag repeats the request's sampled bit), so the dashboard can join the two halves. An existing traceparent set by your code is never overwritten. The header is never added to JaiGateway Monitor's own host.

Browsers sending cross-origin requests to your PHP app need your CORS config to allow the traceparent request header.

Privacy

With send_default_pii off (default) no user, e-mail or IP is attached automatically. Request headers are sent without cookie, authorization, x-api-key (and CSRF tokens). The server additionally scrubs secrets. Use before_send to remove anything else. Note that PHP stack traces in the metadata.traceback string may contain argument values if zend.exception_ignore_args is off; keep it On in production (the default in php.ini-production).

Queue workers and Octane

Request-end hooks do not run in long-lived processes. The Laravel provider flushes and clears the scope on queue Looping, JobProcessed, JobFailed, JobExceptionOccurred, WorkerStopping and Octane RequestTerminated, TaskTerminated, TickTerminated. For your own daemons call Insight::flush() after each unit of work. Events beyond 20 per flush cycle are dropped.

Other frameworks (Slim, Symfony, ...)

Call Insight::init() and registerErrorHandlers() in your front controller. In a PSR-15-free middleware:

Tests

Tests use a fake Insight\Transport; no network is needed. Implement Transport to use Guzzle or another client.

Cron jobs

In Laravel's scheduler you can also use the built-in ->pingBefore($url.'start/')->thenPing($url)->pingOnFailure($url.'fail/'). Nothing here throws.


All versions of monitor with dependencies

PHP Build Version
Package Version
Requires php Version >=8.0
ext-curl Version *
ext-json Version *
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 jaigateway/monitor contains the following files

Loading the files please wait ...