1. honeycombio/buildevents@0.12.0

honeycombio/buildevents@0.12.0

Partner
Sections
Generate traces of your builds for visual inspection on Honeycomb easily using our buildevents utility.
Created: May 22, 2019Version Published: October 17, 2024Releases: 32
Org Usage:
< 25
Categories:

Orb Quick Start Guide

Use CircleCI version 2.1 at the top of your .circleci/config.yml file.

1 version: 2.1

Add the orbs stanza below your version, invoking the orb:

1 2 orbs: buildevents: honeycombio/buildevents@0.12.0

Use buildevents elements in your existing workflows and jobs.

Opt-in to use of uncertified orbs on your organization’s Security settings page.

Usage Examples

example

Basic usage of the buildevents-orb.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 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

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`

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
field_name
the name of the field to add to the surrounding step
Yes
-
string
field_value
the value of the field to add to the surrounding step
Yes
-
string
verbose
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
No
false
boolean

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.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
becommand
-
Yes
-
string
bename
-
Yes
-
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

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
api-key
the API key used to create the marker; defaults to `BUILDEVENT_APIKEY`
No
BUILDEVENT_APIKEY
env_var_name
dataset
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"
No
${BUILDEVENT_DATASET:-buildevents}
string
message
the value displayed on the Honeycomb UI; defaults to the value of `CIRCLE_BUILD_NUM`
No
${CIRCLE_BUILD_NUM}
string
type
all markers of the same type will be shown with the same color in the UI
No
''
string
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`
No
${CIRCLE_BUILD_URL}
string

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.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
result
The final status of the build. Should be either "success" or "failure".
Yes
-
string

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.

Show command Source

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.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
timeout
Timeout after which we consider the build failed, in minutes. Should be at least double your longest expected build.
No
20
integer

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.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
steps
-
Yes
-
steps

Orb Source

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 # This code is licensed from CircleCI to the user under the MIT license. # See here for details: https://circleci.com/developer/orbs/licensing version: 2.1 description: | Generate traces of your builds for visual inspection on Honeycomb easily using our buildevents utility. display: source_url: https://github.com/honeycombio/buildevents-orb commands: add_context: description: | 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` parameters: field_name: description: the name of the field to add to the surrounding step type: string field_value: description: the value of the field to add to the surrounding step type: string verbose: default: false description: | 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 type: boolean steps: - run: command: | if [ "<< parameters.verbose >>" == "true" ] ; then echo "adding the following context to the trace:" echo field: << parameters.field_name >> echo value: << parameters.field_value >> fi echo << parameters.field_name >>=\"<< parameters.field_value >>\" >> /tmp/buildevents/extra_fields.lgfmt name: adding extra field - << parameters.field_name >> berun: description: | 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. parameters: becommand: type: string bename: type: string steps: - run: command: | ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents cmd $(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g') \ $(cat "/tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/span_id") \ "<< parameters.bename >>" -- << parameters.becommand >> name: << parameters.bename >> create_marker: description: | create_marker can run independently without any other buildevent orb commands or setup running beforehand, it only requires curl and jq to be present parameters: api-key: default: BUILDEVENT_APIKEY description: | the API key used to create the marker; defaults to `BUILDEVENT_APIKEY` type: env_var_name dataset: default: ${BUILDEVENT_DATASET:-buildevents} description: | 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" type: string message: default: ${CIRCLE_BUILD_NUM} description: | the value displayed on the Honeycomb UI; defaults to the value of `CIRCLE_BUILD_NUM` type: string type: default: "" description: | all markers of the same type will be shown with the same color in the UI type: string url: default: ${CIRCLE_BUILD_URL} description: | 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` type: string steps: - run: command: | MARKER_BODY=$(jq --null-input \ --arg msg "<< parameters.message>>" \ --arg typ "<< parameters.type >>" \ --arg url "<< parameters.url >>" \ '{"message": $msg, "type": $typ, "url": $url}' ) echo $MARKER_BODY curl "https://api.honeycomb.io/1/markers/<<parameters.dataset>>" \ -X POST -H "X-Honeycomb-Team: ${<< parameters.api-key >>}" \ -d "${MARKER_BODY}" name: create Honeycomb marker finish: description: | 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. parameters: result: description: The final status of the build. Should be either "success" or "failure". type: string steps: - restore_cache: key: buildevents-v0.17.0-2{{ .Environment.BUILDEVENTS_CACHE_VERSION }} - run: command: | ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents \ build $(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g') $(cat /tmp/buildevents/build_start) << parameters.result >> name: Finish the build by sending the root span start_trace: description: | 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. steps: - run: command: | # set up our working environment and timestamp the trace mkdir -p ~/project/bin/be-linux-x86_64 ~/project/bin/be-linux-aarch64 ~/project/bin/be-darwin-arm64/ /tmp/buildevents/ date +%s > /tmp/buildevents/build_start name: setup honeycomb buildevents and start trace - run: command: | BASE_URL=https://github.com/honeycombio/buildevents/releases/download/v0.17.0 curl -q -L -o ~/project/bin/be-linux-x86_64/buildevents ${BASE_URL}/buildevents-linux-amd64 # Note: the URL says arm64, but the path on disk says aarch64 # because that's a thing `uname` gives you. curl -q -L -o ~/project/bin/be-linux-aarch64/buildevents ${BASE_URL}/buildevents-linux-arm64 curl -q -L -o ~/project/bin/be-darwin-arm64/buildevents ${BASE_URL}/buildevents-darwin-arm64 name: downloading buildevents executables - run: command: chmod 755 ~/project/bin/be*/buildevents name: make them executable - save_cache: key: buildevents-v0.17.0-2{{ .Environment.BUILDEVENTS_CACHE_VERSION }} paths: - ~/project/bin - run: command: ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents step $(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g') setup $(cat /tmp/buildevents/build_start) start_trace name: report_step watch_build_and_finish: description: | 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. parameters: timeout: default: 20 description: Timeout after which we consider the build failed, in minutes. Should be at least double your longest expected build. type: integer steps: - restore_cache: key: buildevents-v0.17.0-2{{ .Environment.BUILDEVENTS_CACHE_VERSION }} - run: command: | # set the timeout export BUILDEVENT_TIMEOUT=<< parameters.timeout >> ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents watch $(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g') name: watch then finish build trace with_job_span: description: | 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. parameters: steps: type: steps steps: - restore_cache: key: buildevents-v0.17.0-2{{ .Environment.BUILDEVENTS_CACHE_VERSION }} - run: command: | mkdir -p "/tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}" date +%s > "/tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/start" BUILDEVENTS_SPAN_ID=$(echo "${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}" | sha256sum | awk '{print substr($1, 1, 16)}') echo $BUILDEVENTS_SPAN_ID > "/tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/span_id" # in case this is a bash env, be kind and export the buildevents path, trace ID, and span ID # this orb won't rely on them but consumers of the orb might find it useful # this way steps that are run within a span can use the raw buildevents if desired echo "export BUILDEVENTS_SPAN_ID=$BUILDEVENTS_SPAN_ID" >> $BASH_ENV BUILDEVENTS_TRACE_ID=$(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g') echo "export BUILDEVENTS_TRACE_ID=$BUILDEVENTS_TRACE_ID" >> $BASH_ENV echo "export TRACEPARENT=\"00-${BUILDEVENTS_TRACE_ID}-${BUILDEVENTS_SPAN_ID}-01\"" >> $BASH_ENV echo 'export PATH=$PATH'":~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)" >> $BASH_ENV name: starting span for job - steps: << parameters.steps >> - run: command: echo status=\"failure\" >> /tmp/buildevents/extra_fields.lgfmt name: record failure when: on_fail - run: command: echo status=\"success\" >> /tmp/buildevents/extra_fields.lgfmt name: record success when: on_success - run: command: | # if there are any extra context values, add them if [ -e /tmp/buildevents/extra_fields.lgfmt ] ; then export BUILDEVENT_FILE=/tmp/buildevents/extra_fields.lgfmt fi # go ahead and report the span # choose the right buildevents binary ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents step $(echo $CIRCLE_WORKFLOW_ID | sed 's/-//g') \ $(cat "/tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/span_id") \ $(cat "/tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/start") \ "${CIRCLE_JOB}" name: finishing span for job when: always examples: example: description: Basic usage of the buildevents-orb. usage: 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
Developer Updates
Get tips to optimize your builds
Or join our research panel and give feedback
By submitting this form, you are agreeing to ourTerms of UseandPrivacy Policy.