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

# Instrumentação customizada em PHP

O pacote AppSignal for PHP fornece instrumentações prontas para uso para sua aplicação PHP. No entanto, às vezes você precisa de uma observabilidade mais granular, o que exige instrumentação manual. Para esses casos, use o método `Appsignal::instrument` e personalize os dados enviados ao AppSignal usando os métodos auxiliares.

<Warning>
  Os dados enviados ao AppSignal não devem conter nenhum dado pessoal, como nomes ou
  endereços de e-mail. Sanitize os dados da sua aplicação antes de enviá-los ao
  AppSignal. Se você precisar identificar uma pessoa, use alternativas como um ID de usuário,
  um hash ou um pseudônimo.
</Warning>

## Criando spans

A classe `Appsignal` fornece um helper para criar spans.

### `instrument`

Cria e ativa um novo span. Passe uma closure para que o span seja fechado automaticamente, ou omita-a para gerenciar o ciclo de vida do span manualmente.

#### Com uma closure

Se você usar uma closure, o AppSignal fecha o span ativo automaticamente.

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

#### Sem uma closure

Sem uma closure, o método `instrument` retorna uma instância da classe `ActiveSpan`, um wrapper leve em volta do span do OpenTelemetry e do seu escopo. Feche esse span manualmente chamando `$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

A classe base `Appsignal` fornece métodos auxiliares para adicionar dados customizados a traces ou spans. As seções a seguir descrevem cada helper.

<Note>
  Os exemplos de código abaixo presumem que seu código já está sendo instrumentado (por
  exemplo, dentro de um handler de rota do Laravel ou Symfony). Se seu código ainda não estiver
  instrumentado, você precisa criar um span raiz chamando
  `Appsignal::instrument()` e usar os helpers dentro dele.
</Note>

### `addAttributes`

Adiciona atributos ao span atual.

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

### `addHeaders`

Adiciona cabeçalhos de requisição ao span atual. Se o nome do cabeçalho já existir, o valor é sobrescrito. Os cabeçalhos de requisição são exibidos para traces amostrados no AppSignal. Veja [o guia de personalização de cabeçalhos de requisição](/guides/custom-data/request-headers) para mais informações.

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

### `addTags`

Adiciona tags ao span atual. As tags aparecem como metadados filtráveis no AppSignal e são prefixadas internamente com `appsignal.tag.`.

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

Veja o [guia de tagging](/guides/tagging) para mais informações sobre como as tags funcionam no AppSignal.

### `setAction`

Define o nome da action no span atual. O AppSignal exibe isso como o nome da transação e o usa para agrupar amostras.

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

### `setNamespace`

Define o namespace do span raiz.

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

### `setParams`

Define os parâmetros de query da requisição recebida. O `$params` precisa ser um valor que [pode ser serializado como 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`

Define o payload da requisição recebida. O `$payload` precisa ser um valor que [pode ser serializado como 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()` retorna uma instância de `ActiveSpan` que faz proxy de todos os [métodos](https://open-telemetry.github.io/opentelemetry-php/classes/OpenTelemetry-API-Trace-SpanInterface.html) padrão da `SpanInterface` da API do OpenTelemetry. Se você precisar de controle de baixo nível sobre o span, use esses métodos para anexar dados ou eventos diretamente a ele.

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

someExpensiveMethod();

$activeSpan->end();
```