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

# honeycombio/buildevents

Generate traces of your builds for visual inspection on Honeycomb easily using our buildevents utility.


## Commands

### add_context

add_context is a function to add additional fields to the span
representing this job. It can be called multiple times, each with one
value. It is useful for adding things like artifact sizes, parameters to
the job, and so on. Call this with two arguments - the field name and the
field value. Both name and value must be strings, but numbers will be
coerced before getting sent to Honeycomb. Names must be single words;
values can be longer strings. This must be used within the context of
`with_job_span`


| Parameter | Type | Default | Description |
|---|---|---|---|
| `field_name` | string |  | the name of the field to add to the surrounding step |
| `field_value` | string |  | the value of the field to add to the surrounding step |
| `verbose` | boolean | false | if set to `true`, the extra context field name and content will be
evaluated and echoed to your build log in addition to being sent to
Honeycomb
 |

### berun

berun executes a command and creates a span representing that command. The
bename parameter will be the name of the span. berun must be used within a
step decorated by with_job_span.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `becommand` | string |  |  |
| `bename` | string |  |  |

### create_marker

create_marker can run independently without any other buildevent orb commands
or setup running beforehand, it only requires curl and jq to be present


| Parameter | Type | Default | Description |
|---|---|---|---|
| `api-key` | env_var_name | BUILDEVENT_APIKEY | the API key used to create the marker; defaults to `BUILDEVENT_APIKEY`
 |
| `dataset` | string | ${BUILDEVENT_DATASET:-buildevents} | the dataset within which to create the marker; if not explicitly set,
will use the environment variable `BUILDEVENT_DATASET`, and if that is
not set, will fallback to the literal value "buildevents"
 |
| `message` | string | ${CIRCLE_BUILD_NUM} | the value displayed on the Honeycomb UI; defaults to the value of `CIRCLE_BUILD_NUM`
 |
| `type` | string |  | all markers of the same type will be shown with the same color in the UI
 |
| `url` | string | ${CIRCLE_BUILD_URL} | if a URL is specified along with a message, the message will be shown as
a link in the UI, and clicking it will take you to the URL; defaults to
the value of `CIRCLE_BUILD_URL`
 |

### finish

finish is an alternative to watch_build_and_finish. If you can't create a
CircleCI API token or want to manually finish the trace, you can use this
command to do so. If you can, it's recommended that you use
watch_build_and_finish instead of this command.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `result` | string |  | The final status of the build. Should be either "success" or "failure". |

### start_trace

start_trace should be run in a job all on its own at the very beginning of
a build. This job initializes the buildevents config, downloads the
buildevents binary, and otherwise gets the build environment ready for the
rest of the jobs.


### watch_build_and_finish

watch_build_and_finish will poll the CircleCI API to determine when the
build is done. It should be its own job dependent on the job that runs
start_trace, and no job should depend on it finishing.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `timeout` | integer | 20 | Timeout after which we consider the build failed, in minutes. Should be at least double your longest expected build. |

### with_job_span

Starts a span that will record the length of this job.
Takes `steps`, just like a normal command, and runs them.
When the steps are done, it records the success or failure of the job.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `steps` | steps |  |  |

## Examples

### example

Basic usage of the buildevents-orb.

```yaml
version: '2.1'
orbs:
  buildevents: honeycombio/buildevents@0.12.0
  shellcheck: circleci/shellcheck@3.2.0
jobs:
  build:
    docker:
      - image: cimg/base:stable
    steps:
      - buildevents/with_job_span:
          steps:
            - buildevents/add_context:
                field_name: arch
                field_value: $(uname -m)
            - run: yarn --immutable
            - run: >
                # buildevents can be used directly for even more spans
                buildevents cmd $(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g')
                $BUILDEVENTS_SPAN_ID yarn-test -- yarn test
  setup:
    docker:
      - image: cimg/base:stable
    steps:
      - buildevents/start_trace
  watch:
    docker:
      - image: cimg/base:stable
    steps:
      - buildevents/watch_build_and_finish
workflows:
  ci:
    jobs:
      - setup
      - watch:
          requires:
            - setup
      - build:
          requires:
            - setup
```