motadata-apm/custom-instrumentation

Motadata APM custom instrumentation helpers for OpenTelemetry spans in PHP.

v1.0.0 2026-02-20 07:51 UTC

Requires

• php: >=8.1 <=8.4
• open-telemetry/api: ^1.3

proprietary

• Motadata Engineering

• apm
• instrumentation
• tracing
• opentelemetry
• motadata

README

Lightweight utilities for adding validated, namespaced custom attributes to Motadata Instrumentation spans in PHP. Designed to keep instrumentation safe, consistent, and easy to adopt.

Table of Contents

• Overview
• Requirements
• Installation
• Quick Start
• API at a Glance
• Behavior & Validation
• Best Practices
• Support
• License

Overview

Motadata APM Custom Instrumentation helps you attach business context to traces without risking invalid attributes or inconsistent naming. Keys are automatically namespaced, inputs are validated, and the API is safe to use across concurrent requests.

Prerequisite: Instrument your app first with Motadata Auto Instrumentation so the span context is available.

Requirements

• PHP >= 8.1 and <= 8.4
• Motadata Agent (8.1.2+)

Installation

There are several ways to add this package to your project. Note that if this package is not yet published on Packagist, you must use the VCS or Local Path methods.

1. Via Composer CLI

If the package is published on Packagist:

composer require motadata-apm/custom-instrumentation

2. Manual Installation (composer.json)

Add the package to your require block:

{
    "require": {
        "motadata-apm/custom-instrumentation": "^1.0"
    }
}

Then run:

composer update motadata-apm/custom-instrumentation

3. Via VCS Repository (GitHub/Private Git)

Use this method to pull directly from the Git repository (e.g., for private use or internal testing).

1. Add the repository to your composer.json:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/motadata2025/motadata-apm-custom-instrumentation-php"
        }
    ],
    "require": {
        "motadata-apm/custom-instrumentation": "dev-main"
    }
}

1. Run composer update.

Authentication for Private Repositories

When using the VCS method with a private repository, you must provide credentials.

Recommended: Using the CLI

Run this command to store your GitHub Personal Access Token (PAT) securely:

composer config --global github-oauth.github.com <your-token>

Manual: auth.json

Alternatively, create an auth.json file in your project root or in ~/.composer/:

{
    "github-oauth": {
        "github.com": "your-personal-access-token"
    }
}

Warning: Never commit auth.json to version control. Add it to your .gitignore.

Note for Auto-Instrumentation Users: If you are using the Motadata PHP Auto-Instrumentation script, it may occasionally revert composer.json or remove this package during dependency synchronization. If the package is missing from your composer.json after instrumentation, simply re-add the package details as shown in the installation steps above and run composer update.

Quick Start

<?php

use Motadata\Apm\CustomInstrumentation;

try {
    CustomInstrumentation::setInt('apm.user.id', 98765);
    CustomInstrumentation::setInt('apm.order.id', 12345);
    CustomInstrumentation::setFloat('apm.order.amount', 199.99);
    CustomInstrumentation::set('apm.request.success', true);
    CustomInstrumentation::setString('apm.user.name', 'john.doe');
    CustomInstrumentation::setStringArray('apm.tags', ['api', 'production', 'critical']);
} catch (Exception $exception) {
    error_log('Failed to set custom attributes: ' . $exception->getMessage());
}

Keys are automatically prefixed with apm. when missing, but prefer providing the prefix yourself for consistency. All setters throw Exception on invalid input or missing span context, so keep calls wrapped in try/catch.

API at a Glance

Scalar

Method	Parameter
set(string $key, bool $value)	bool
setInt(string $key, int $value)	int
setFloat(string $key, float $value)	float (finite)
setString(string $key, string $value)	string

Arrays

Method	Parameter
setBoolArray(string $key, array $values)	bool[]
setIntArray(string $key, array $values)	int[]
setFloatArray(string $key, array $values)	float[] (finite)
setStringArray(string $key, array $values)	string[]

Behavior & Validation

• Keys auto-prefix to apm. when absent, are lowercased, and are trimmed before validation.
• Keys allow only alphanumeric characters and dots.
• Nulls are removed from arrays; arrays must retain at least one non-null value.
• Float inputs reject NaN or Infinity.
• Throws Exception for invalid input or when no active span is present.

Best Practices

• Use descriptive, hierarchical keys already prefixed with apm. (e.g., apm.order.id, apm.order.items).
• Choose correct types: IDs as int, metrics as float, flags as bool.
• Wrap calls in try/catch and log errors so observability never breaks business flow.
• Use array setters for collections; let null filtering happen inside the library.
• Keep key naming consistent across services to simplify querying.

Support

• Email: [e-mail]
• Issues: https://github.com/motadata2025/motadata-apm-custom-instrumentation-php/issues

License

Copyright (c) Motadata 2026. All rights reserved.

Proprietary software; see LICENSE for full terms.