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.
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
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 | 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 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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
becommand | - | Yes | - | string |
bename | - | Yes | - | string |
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 | 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 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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
result | The final status of the build. Should be either "success" or "failure". | Yes | - | string |
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 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 | 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 |
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 | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
steps | - | Yes | - | steps |
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