> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instrumentation personnalisée PHP

Le paquet AppSignal pour PHP fournit des instrumentations prêtes à l'emploi pour votre application PHP. Cependant, vous avez parfois besoin d'une observabilité plus fine, ce qui nécessite une instrumentation manuelle. Pour ces cas, utilisez la méthode `Appsignal::instrument` et personnalisez les données envoyées à AppSignal à l'aide des méthodes d'aide.

<Warning>
  Les données envoyées à AppSignal ne doivent contenir aucune donnée personnelle, telle que des noms ou
  des adresses e-mail. Assainissez les données de votre application avant de les envoyer à
  AppSignal. Si vous devez identifier une personne, utilisez des alternatives comme un identifiant utilisateur,
  un hachage ou un pseudonyme.
</Warning>

## Créer des spans

La classe `Appsignal` fournit une aide pour créer des spans.

### `instrument`

Crée et active un nouveau span. Passez une closure pour que le span soit fermé automatiquement, ou omettez-la pour gérer le cycle de vie du span manuellement.

#### Avec une closure

Si vous utilisez une closure, AppSignal ferme le span actif automatiquement.

```php PHP theme={null}
Appsignal::instrument(
	name: 'process-order',
	attributes: ['order_id' => $orderId],
	closure: function () {
		// do work here
		Appsignal::setAttributes(['order_status' => 'processed']);
	},
);
```

#### Sans closure

Sans closure, la méthode `instrument` retourne une instance de la classe `ActiveSpan`, un fin wrapper autour du span OpenTelemetry et de sa portée. Fermez ce span manuellement en appelant `$span->end()`.

```php PHP theme={null}
$activeSpan = Appsignal::instrument(
	name: 'upload-file',
	attributes: ['file_name' => $filename],
);

try {
    uploadFile($file);
} catch (Throwable $e) {
    Appsignal::setError($e);
} finally {
    $activeSpan->end();
}
```

## Helpers

La classe de base `Appsignal` fournit des méthodes d'aide pour ajouter des données personnalisées aux traces ou aux spans. Les sections suivantes décrivent chaque méthode d'aide.

<Note>
  Les exemples de code ci-dessous supposent que votre code est déjà instrumenté (par
  exemple, à l'intérieur d'un gestionnaire de route Laravel ou Symfony). Si votre code n'est pas
  déjà instrumenté, vous devez créer un span racine en appelant
  `Appsignal::instrument()` et utiliser les méthodes d'aide à l'intérieur de celui-ci.
</Note>

### `addAttributes`

Ajoute des attributs au span actuel.

```php PHP theme={null}
Appsignal::addAttributes([
    'user_id'   => $user->id,
    'user_plan' => $user->plan,
]);
```

### `addHeaders`

Ajoute des en-têtes de requête au span actuel. Si le nom de l'en-tête existe déjà, la valeur est écrasée. Les en-têtes de requête sont affichés pour les traces échantillonnées dans AppSignal. Consultez [le guide de personnalisation des en-têtes de requête](/guides/custom-data/request-headers) pour plus d'informations.

```php PHP theme={null}
Appsignal::addHeaders(['custom-header' => 'some-value']);
```

### `addTags`

Ajoute des tags au span actuel. Les tags apparaissent comme des métadonnées filtrables dans AppSignal et sont préfixés en interne par `appsignal.tag.`.

```php PHP theme={null}
Appsignal::addTags([
    'locale'  => 'en',
    'version' => '2.1.0',
]);
```

Consultez le [guide de tagging](/guides/tagging) pour plus d'informations sur le fonctionnement des tags dans AppSignal.

### `setAction`

Définit le nom de l'action sur le span actuel. AppSignal l'affiche comme nom de transaction et l'utilise pour regrouper les échantillons.

```php PHP theme={null}
Appsignal::setAction('OrdersController::create');
```

### `setNamespace`

Définit le namespace du span racine.

```php PHP theme={null}
Appsignal::setNamespace('admin');
```

### `setParams`

Définit les paramètres de requête de la requête entrante. Les `$params` doivent être une valeur qui [peut être sérialisée en JSON](https://www.php.net/manual/en/function.json-encode.php).

```php PHP theme={null}
$params = [
    'param1' => 'value1',
    'param2' => 'value2',
    'nested' => [
        'param3' => 'value3',
        'param4' => 'value4',
    ],
];

Appsignal::setParams($params);
```

### `setPayload`

Définit le payload de la requête entrante. Le `$payload` doit être une valeur qui [peut être sérialisée en JSON](https://www.php.net/manual/en/function.json-encode.php).

```php PHP theme={null}
$payload = [
    'key1' => 'value1',
    'key2' => 'value2',
    'nested' => [
        'key3' => 'value3',
        'key4' => 'value4',
    ],
];

Appsignal::setPayload($payload);
```

## `ActiveSpan`

`Appsignal::instrument()` retourne une instance `ActiveSpan` qui agit comme un proxy pour toutes les [méthodes](https://open-telemetry.github.io/opentelemetry-php/classes/OpenTelemetry-API-Trace-SpanInterface.html) standard de l'API `SpanInterface` d'OpenTelemetry. Si vous avez besoin d'un contrôle de bas niveau sur le span, utilisez ces méthodes pour y attacher directement des données ou des événements.

```php PHP theme={null}
$activeSpan = Appsignal::instrument('render-report');
$activeSpan->setAttribute('report.type', 'pdf');
$activeSpan->addEvent('rendering-started');

someExpensiveMethod();

$activeSpan->end();
```