PHPackages                             motadata-apm/custom-instrumentation - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. motadata-apm/custom-instrumentation

ActiveLibrary[Logging & Monitoring](/categories/logging)

motadata-apm/custom-instrumentation
===================================

Motadata APM custom instrumentation helpers for OpenTelemetry spans in PHP.

v1.0.0(2mo ago)00proprietaryPHPPHP >=8.1 <=8.4

Since Feb 20Pushed 2mo agoCompare

[ Source](https://github.com/motadata2025/motadata-apm-custom-instrumentation-php)[ Packagist](https://packagist.org/packages/motadata-apm/custom-instrumentation)[ Docs](https://www.motadata.com/aiops-platform/)[ RSS](/packages/motadata-apm-custom-instrumentation/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (3)Used By (0)

Motadata APM Custom Instrumentation for PHP
===========================================

[](#motadata-apm-custom-instrumentation-for-php)

[![PHP Version](https://camo.githubusercontent.com/4c56f430b0df82562bafb194b5e9c764c61d86a3607dce55f6bdf9014a45b0a5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e315f2d2d5f382e342d626c75652e737667)](https://www.php.net/)[![License](https://camo.githubusercontent.com/41e639cac81d867e862c30b25ebe94d6bb044255bfff41f12a03d0f0f056d9c9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d50726f70726965746172792d7265642e737667)](LICENSE)

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
-----------------

[](#table-of-contents)

- [Overview](#overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [API at a Glance](#api-at-a-glance)
- [Behavior & Validation](#behavior--validation)
- [Best Practices](#best-practices)
- [Support](#support)
- [License](#license)

---

Overview
--------

[](#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](https://docs.motadata.com/motadata-aiops-docs/apm/apm-in-motadata/)** so the span context is available.

---

Requirements
------------

[](#requirements)

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

---

Installation
------------

[](#installation)

There are several ways to add this package to your project. Note that if this package is not yet published on [Packagist](https://packagist.org), you **must** use the [VCS](#3-via-vcs-repository-githubprivate-git) or [Local Path](#4-local-path-for-development) methods.

### 1. Via Composer CLI

[](#1-via-composer-cli)

If the package is published on Packagist:

```
composer require motadata-apm/custom-instrumentation
```

### 2. Manual Installation (`composer.json`)

[](#2-manual-installation-composerjson)

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)

[](#3-via-vcs-repository-githubprivate-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"
    }
}
```

2. Run `composer update`.

### 4. Local Path (For Development)

[](#4-local-path-for-development)

Use this method if you are working on the package locally and want to test it in another project without pushing to Git.

```
{
    "repositories": [
        {
            "type": "path",
            "url": "../path/to/motadata-apm-custom-instrumentation-php",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "motadata-apm/custom-instrumentation": "*"
    }
}
```

---

Authentication for Private Repositories
---------------------------------------

[](#authentication-for-private-repositories)

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

### Recommended: Using the CLI

[](#recommended-using-the-cli)

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

```
composer config --global github-oauth.github.com
```

### Manual: `auth.json`

[](#manual-authjson)

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
-----------

[](#quick-start)

```