let's try to separate out commands

@orb.yml

@@ -0,0 +1,7 @@
+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.yml

@@ -0,0 +1,33 @@
+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:
+    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
+      Hoenycomb
+    type: boolean
+    default: false
+steps:
+  - run:
+      name: adding extra field - << parameters.field_name >>
+      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

commands/berun.yml

@@ -0,0 +1,16 @@
+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:
+  bename:
+    type: string
+  becommand:
+    type: string
+steps:
+  - run:
+      name: << parameters.bename >>
+      command: |
+        ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents cmd $CIRCLE_WORKFLOW_ID \
+          $(cat /tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/span_id) \
+          "<< parameters.bename >>" -- << parameters.becommand >>

commands/create_marker.yml

@@ -0,0 +1,47 @@
+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:
+    description: |
+      the API key used to create the marker; defaults to `BUILDEVENT_APIKEY`
+    type: env_var_name
+    default: BUILDEVENT_APIKEY
+  dataset:
+    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
+    default: "${BUILDEVENT_DATASET:-buildevents}"
+  message:
+    description: |
+      the value displayed on the Honeycomb UI; defaults to the value of `CIRCLE_BUILD_NUM`
+    type: string
+    default: "${CIRCLE_BUILD_NUM}"
+  type:
+    description: |
+      all markers of the same type will be shown with the same color in the UI
+    type: string
+    default: ""
+  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
+    default: "${CIRCLE_BUILD_URL}"
+steps:
+  - run:
+      name: create Honeycomb marker
+      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}"

commands/finish.yml

@@ -0,0 +1,17 @@
+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.15.0-1{{ .Environment.BUILDEVENTS_CACHE_VERSION }}
+  - run:
+      name: Finish the build by sending the root span
+      command: |
+        ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents \
+        build $CIRCLE_WORKFLOW_ID $(cat /tmp/buildevents/build_start) << parameters.result >>

commands/start_trace.yml

@@ -0,0 +1,31 @@
+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:
+      name: setup honeycomb buildevents and start trace
+      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
+  - run:
+      name: downloading buildevents executables
+      command: |
+        BASE_URL=https://github.com/honeycombio/buildevents/releases/download/v0.15.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
+  - run:
+      name: make them executable
+      command: chmod 755 ~/project/bin/be*/buildevents
+  - save_cache:
+      key: buildevents-v0.15.0-1{{ .Environment.BUILDEVENTS_CACHE_VERSION }}
+      paths:
+        - ~/project/bin
+  - run:
+      name: report_step
+      command: ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents step $CIRCLE_WORKFLOW_ID setup $(cat /tmp/buildevents/build_start) start_trace

commands/watch_build_and_finish.yml

@@ -0,0 +1,18 @@
+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:
+    description: Timeout after which we consider the build failed, in minutes. Should be at least double your longest expected build.
+    type: integer
+    default: 20
+steps:
+  - restore_cache:
+      key: buildevents-v0.15.0-1{{ .Environment.BUILDEVENTS_CACHE_VERSION }}
+  - run:
+      name: watch then finish build trace
+      command: |
+        # set the timeout
+        export BUILDEVENT_TIMEOUT=<< parameters.timeout >>
+        ~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)/buildevents watch $CIRCLE_WORKFLOW_ID

commands/with_job_span.yml

@@ -0,0 +1,49 @@
+parameters:
+  steps:
+    type: steps
+steps:
+  - restore_cache:
+      key: buildevents-v0.15.0-1{{ .Environment.BUILDEVENTS_CACHE_VERSION }}
+  - run:
+      name: starting span for job
+      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 $1}')
+        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 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
+        echo 'export PATH=$PATH'":~/project/bin/be-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m)" >> $BASH_ENV
+
+  ### run the job's steps
+  - steps: << parameters.steps >>
+
+  - run:
+      name: record failure
+      command: echo status=\"failure\" >> /tmp/buildevents/extra_fields.lgfmt
+      when: on_fail
+
+  - run:
+      name: record success
+      command: echo status=\"success\" >> /tmp/buildevents/extra_fields.lgfmt
+      when: on_success
+
+  - run:
+      name: finishing span for job
+      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 $CIRCLE_WORKFLOW_ID \
+          $(cat /tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/span_id) \
+          $(cat /tmp/buildevents/${CIRCLE_JOB}-${CIRCLE_NODE_INDEX}/start) \
+          ${CIRCLE_JOB}
+      when: always