> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# blackfireio/agent

This orb installs and configures Blackfire agent and CLI tool.
You need an account on https://blackfire.io to use this orb.

Blackfire is the Code Performance Management solution for developers
to find and fix performance bottlenecks in dev, test/staging and production.

The "agent" is the component that aggregates profile data collected by the probe from your application engine
(PHP, Python...), before sending it to Blackfire.io servers so that you can display and analyze it.


## Commands

### register

Registers Blackfire agent and CLI tool with your credentials passed as environment variables.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `server_id` | env_var_name | BLACKFIRE_SERVER_ID | Environment variable name in which your server ID is stored. |
| `server_token` | env_var_name | BLACKFIRE_SERVER_TOKEN | Environment variable name in which your server token is stored. |
| `client_id` | env_var_name | BLACKFIRE_CLIENT_ID | Environment variable name in which your client ID is stored. |
| `client_token` | env_var_name | BLACKFIRE_CLIENT_TOKEN | Environment variable name in which your client token is stored. |

### setup

Installs and configures Blackfire agent.
setup command MUST BE CALLED BEFORE.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `server_id` | env_var_name | BLACKFIRE_SERVER_ID | Environment variable name in which your server ID is stored. |
| `server_token` | env_var_name | BLACKFIRE_SERVER_TOKEN | Environment variable name in which your server token is stored. |
| `client_id` | env_var_name | BLACKFIRE_CLIENT_ID | Environment variable name in which your client ID is stored. |
| `client_token` | env_var_name | BLACKFIRE_CLIENT_TOKEN | Environment variable name in which your client token is stored. |

### setup-redhat

Installs and configures Blackfire agent in a RedHat environment.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `server_id` | env_var_name | BLACKFIRE_SERVER_ID | Environment variable name in which your server ID is stored. |
| `server_token` | env_var_name | BLACKFIRE_SERVER_TOKEN | Environment variable name in which your server token is stored. |
| `client_id` | env_var_name | BLACKFIRE_CLIENT_ID | Environment variable name in which your client ID is stored. |
| `client_token` | env_var_name | BLACKFIRE_CLIENT_TOKEN | Environment variable name in which your client token is stored. |

### build-trigger

Triggers a Blackfire build using a webhook.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `endpoint` | string |  | Endpoint for reaching your application out. |
| `environment` | string |  | Environment name or UUID on which the build is triggered.
Part of the environment name can be used.
 |
| `token` | string |  | Build Token to use for the build.
More information at https://blackfire.io/docs/cookbooks/builds/builds-webhook#build-tokens

It is strongly recommended to use a project environment variable and use it to fill this parameter.
 |
| `title` | string | CircleCI '${CIRCLE_JOB}' ${CIRCLE_BUILD_NUM} | Title of the triggered build. |
| `external-id` | string | ${CIRCLE_SHA1} | A unique identifier for the build. Defaults to the latest git commit sha1. |
| `external-parent-id` | string |  | The unique identifier of the parent build, to compare with the current build, like the reference Git commit sha1. |
| `external-url` | string | ${CIRCLE_BUILD_URL} | A URL related to the build, like a Pull Request. |
| `http-username` | string |  | The username for HTTP Basic authentication on the endpoint. |
| `http-password` | string |  | The password for HTTP Basic authentication on the endpoint. |
| `ip` | string |  | The IP for forcing DNS. |
| `ssl-no-verify` | boolean | false | If true, disables SSL certificates verification (this is insecure) |

## Examples

### install_agent

Easily install and configure the Blackfire agent

```yaml
version: 2.1
orbs:
  blackfire-agent: blackfireio/agent@x.y
jobs:
  blackfire-agent-example:
    docker:
      - image: circleci/php:7.3-node
    steps:
      - checkout
      - blackfire-agent/setup
```

### build_trigger

Trigger a Blackfire build as described in https://blackfire.io/docs/reference-guide/builds-and-integrations

```yaml
version: 2.1
orbs:
  blackfire-agent: blackfireio/agent@x.y
jobs:
  blackfire-build-example:
    docker:
      - image: circleci/php:7.4-node
    steps:
      - checkout
      - blackfire-agent/build-trigger:
          endpoint: https://staging.my-webapp.tld/
          environment: My Blackfire Environment Name
          token: ${BLACKFIRE_BUILD_TOKEN}
```