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

# Benutzerdefinierte PHP-Instrumentierung

Das AppSignal-für-PHP-Paket bietet Out-of-the-box-Instrumentierungen für Ihre PHP-Anwendung. Manchmal benötigen Sie jedoch eine feingranulare Observability, die eine manuelle Instrumentierung erfordert. Verwenden Sie in diesen Fällen die Methode `Appsignal::instrument` und passen Sie die an AppSignal gesendeten Daten mit den Hilfsmethoden an.

<Warning>
  An AppSignal gesendete Daten dürfen keine personenbezogenen Daten enthalten, wie Namen oder
  E-Mail-Adressen. Bereinigen Sie die Daten Ihrer Anwendung, bevor Sie sie an
  AppSignal senden. Wenn Sie eine Person identifizieren müssen, verwenden Sie Alternativen wie eine Benutzer-ID,
  einen Hash oder ein Pseudonym.
</Warning>

## Spans erstellen

Die Klasse `Appsignal` stellt eine Hilfsmethode zum Erstellen von Spans bereit.

### `instrument`

Erstellt und aktiviert einen neuen Span. Übergeben Sie eine Closure, damit der Span automatisch geschlossen wird, oder lassen Sie sie weg, um den Lebenszyklus des Spans manuell zu verwalten.

#### Mit einer Closure

Wenn Sie eine Closure verwenden, schließt AppSignal den aktiven Span automatisch.

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

#### Ohne Closure

Ohne Closure gibt die Methode `instrument` eine Instanz der Klasse `ActiveSpan` zurück, einen schlanken Wrapper um den OpenTelemetry-Span und dessen Scope. Schließen Sie diesen Span manuell, indem Sie `$span->end()` aufrufen.

```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();
}
```

## Hilfsmethoden

Die Basisklasse `Appsignal` stellt Hilfsmethoden bereit, um Traces oder Spans benutzerdefinierte Daten hinzuzufügen. Die folgenden Abschnitte beschreiben jede Hilfsmethode.

<Note>
  Die folgenden Codebeispiele setzen voraus, dass Ihr Code bereits instrumentiert wird (zum
  Beispiel innerhalb eines Laravel- oder Symfony-Route-Handlers). Wenn Ihr Code noch nicht
  instrumentiert ist, müssen Sie einen Root-Span erstellen, indem Sie
  `Appsignal::instrument()` aufrufen, und die Hilfsmethoden darin verwenden.
</Note>

### `addAttributes`

Fügt dem aktuellen Span Attribute hinzu.

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

### `addHeaders`

Fügt dem aktuellen Span Request-Header hinzu. Wenn der Header-Name bereits existiert, wird der Wert überschrieben. Request-Header werden für gesampelte Traces in AppSignal angezeigt. Weitere Informationen finden Sie im [Leitfaden zur Anpassung von Request-Headern](/guides/custom-data/request-headers).

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

### `addTags`

Fügt dem aktuellen Span Tags hinzu. Tags erscheinen in AppSignal als filterbare Metadaten und werden intern mit `appsignal.tag.` präfixiert.

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

Weitere Informationen zur Funktionsweise von Tags in AppSignal finden Sie im [Tagging-Leitfaden](/guides/tagging).

### `setAction`

Legt den Aktionsnamen für den aktuellen Span fest. AppSignal zeigt diesen als Transaktionsnamen an und verwendet ihn, um Samples zu gruppieren.

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

### `setNamespace`

Legt den Namespace des Root-Spans fest.

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

### `setParams`

Legt die Query-Parameter der eingehenden Anfrage fest. Die `$params` müssen ein Wert sein, der [als JSON serialisiert werden kann](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`

Legt den Payload der eingehenden Anfrage fest. Das `$payload` muss ein Wert sein, der [als JSON serialisiert werden kann](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()` gibt eine `ActiveSpan`-Instanz zurück, die alle Standard-OpenTelemetry-API-`SpanInterface`-[Methoden](https://open-telemetry.github.io/opentelemetry-php/classes/OpenTelemetry-API-Trace-SpanInterface.html) durchreicht. Wenn Sie Low-Level-Kontrolle über den Span benötigen, verwenden Sie diese Methoden, um Daten oder Events direkt an ihn anzuhängen.

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

someExpensiveMethod();

$activeSpan->end();
```