Download the PHP package stellarsecurity/application-insights-laravel without Composer

Stellar Application Insights for Laravel

A lightweight Laravel package that sends telemetry to Azure Application Insights (requests, exceptions, and custom events).

Built by https://stellarsecurity.com

This package is designed to be safe by default:

• Telemetry must never break your application
• Queue sending is disabled by default to avoid silent data loss
• URL query parameters are disabled by default to reduce accidental exposure of request data
• Sensitive query parameter values are masked by default when query capture is enabled
• Query parameter privacy behavior can be controlled with .env rules
• Sensitive telemetry properties are masked before they are sent
• Connection String is the preferred configuration (modern App Insights)

Requirements

• PHP >= 8.1
• Laravel 10+ (also compatible with Laravel 11/12 when using matching illuminate components)
• Guzzle 7.x or 8.x

Installation

Configuration

Publish the package config:

Then configure the package through your .env file.

Recommended: Connection String

Set one of the following in your .env:

You may also use the package-specific key:

Fallback: Instrumentation Key only

Query parameters in request URLs

Query parameters are excluded from request telemetry by default.

For example, this incoming request:

is recorded as:

To include query parameters in Application Insights request URLs, enable:

After changing telemetry configuration, rebuild Laravel's configuration cache:

Query parameter privacy rules

When query parameter capture is enabled, each parameter can have its own JSON rule.

STELLAR_AI_QUERY_PARAM_RULES is a JSON object where each key is a parameter name or wildcard pattern and each value describes what should happen to that parameter:

The same value formatted as JSON is:

Parameter matching is case-insensitive and supports * and ? wildcards.

Supported actions:

show_first and show_last require a non-negative integer characters value.

Example request:

With:

it is recorded as the equivalent of:

The mask marker is URL-encoded in the actual telemetry URL.

Per-rule mask markers

A rule can override the global mask marker. This is useful when different parameters need different masking formats:

If a rule does not define mask, the package uses STELLAR_AI_QUERY_PARAM_MASK.

Built-in sensitive rules

For backward compatibility and secure defaults, the package still masks parameter names containing sensitive fragments such as password, token, authorization, auth, api_key, secret, email, username, ip, ip_address, user_agent, and wipe_token.

Built-in rules are applied only when no custom rule matched. This means custom JSON rules can deliberately override them:

To disable the built-in query parameter rules completely:

This setting only changes query parameter handling. The package's general telemetry-property sanitization remains protected by its built-in sensitive-key behavior.

Default action for unmatched parameters

By default, unmatched non-sensitive query parameters are kept, preserving the package's previous behavior:

The default action supports keep, mask, or drop. Partial masking belongs in a parameter-specific JSON rule because it requires a characters value.

A strict allowlist-style policy can mask everything except explicitly approved parameters:

This is the recommended configuration when you want explicit control over every query parameter that may appear in telemetry.

Overlapping wildcard rules

For most installations, the JSON object format above is the simplest option. Rules are evaluated in their decoded order and the first matching rule wins.

If overlapping wildcard precedence must be explicit, an ordered JSON list is also accepted:

Each list item uses parameter as the name/pattern plus the same action, characters, and optional mask fields.

Custom global mask marker

The default mask marker is <removed>:

It can be changed, for example:

A complete example:

Invalid JSON fails closed: query parameter values are masked instead of being exposed. An explicitly matched rule with an invalid action or invalid characters value also fails closed to full masking. An invalid default action fails closed to mask.

Example config (config/stellar-ai.php)

Queue mode (optional)

By default, telemetry is sent directly (HTTP) to avoid losing data if no workers are running.

If you want to use queues:

Then ensure a worker is running in production:

If you enable queue mode without a running worker, telemetry will be delayed and may appear missing.

What is tracked

Depending on your middleware/service wiring, the package can track:

• HTTP requests
• Exceptions
• Custom events (EventData)
• Dependencies (if you emit dependency telemetry)

Viewing data in Azure

In Azure Portal -> Application Insights -> Logs (Analytics), run:

If you only want requests:

To inspect captured URLs and verify query parameter handling when enabled:

Common troubleshooting

I see no data at all

1. Confirm your app is using the correct Application Insights resource.
2. Confirm a valid instrumentation key is resolved.
   • If using a connection string, it must include InstrumentationKey=....
3. If queue mode is enabled, confirm workers are running.
4. Clear and rebuild config cache after changing .env:

Query parameters are missing

Query parameter capture is disabled by default. Enable it with:

Then rebuild the Laravel configuration cache:

A query parameter is unexpectedly masked

Check these settings in this order:

1. STELLAR_AI_QUERY_PARAM_RULES - first matching custom rule wins.
2. STELLAR_AI_QUERY_PARAM_USE_BUILTIN_SENSITIVE_RULES - built-in sensitive-name protection runs after custom rules.
3. STELLAR_AI_QUERY_PARAM_DEFAULT_ACTION - applies when nothing else matched.

After editing .env, rebuild the Laravel configuration cache.

Azure "Search" looks empty, but Logs has data

This is usually a UI filtering issue. Use Logs (Analytics) queries to confirm ingestion.

Local verification

After installing dependencies, you can run the package's query-rule smoke test directly:

There is no separate package build step. In a Laravel application, publish the configuration and rebuild Laravel's configuration cache after changing .env values:

License

MIT