Add beeline-style propagation of the cmd context to called commands

When using something like https://github.com/puppetlabs/rspec_honeycomb_formatter , it would be nice to connect the individual spans to the bigger picture of the buildevent steps and commands. This change uses the beeline's `PropagationContext` marshaling to pass on the current event to the called command.

In the style of the rest of the HONEYCOMB_* environment variables and the similarily named `X-Honeycomb-Trace` HTTP header, this establishes `HONEYCOMB_TRACE` to pass the propagation context to other processes.

README.md

@@ -170,6 +170,36 @@ jobs:
  - run: $GOPATH/bin/buildevents cmd $TRAVIS_BUILD_ID $STEP_SPAN_ID go-test -- go test -timeout 2m -mod vendor ./...
 ```
 
+## Attaching more traces from your build and test process
+
+Every command running through `buildevents cmd` will receive a `HONEYCOMB_TRACE` environment variable that contains a marshalled trace propagation context. This can be used to connect more spans to this trace.
+
+Ruby Beeline example:
+```ruby
+# at the very start of the command
+# establish a command-level span, linking to the buildevent
+process_span = Honeycomb.start_span(name: File.basename($PROGRAM_NAME), serialized_trace: ENV['HONEYCOMB_TRACE'])
+Honeycomb.add_field_to_trace('process.full_name', $PROGRAM_NAME)
+
+# if you're not passing sensitive information through CLI args, enable this for more insights.
+#Honeycomb.add_field_to_trace('process.args', ARGV)
+
+# override the HONEYCOMB_TRACE for sub-processes
+ENV['HONEYCOMB_TRACE'] = process_span.to_trace_header
+
+# ensure that the process_span is sent before the process terminates
+at_exit do
+ if $ERROR_INFO&.is_a?(SystemExit)
+ process_span.add_field('process.exit_code', $ERROR_INFO.status)
+ elsif $ERROR_INFO
+ process_span.add_field('process.exit_code', $ERROR_INFO.class.name)
+ else
+ process_span.add_field('process.exit_code', 'unknown')
+ end
+ process_span.send
+end
+```
+
 # Putting it all together
 
 We've covered each of the three modes in which `buildevents` is invoked and shown abbreviated examples for each one. Now it's time to look at an entire config to see how they interact: installation, running a build, and finally reporting the whole thing.

cmd_cmd.go

@@ -11,6 +11,7 @@ import (
  "github.com/spf13/cobra"
 
  libhoney "github.com/honeycombio/libhoney-go"
+ propagation "github.com/honeycombio/beeline-go/propagation"
 )
 
 func commandCmd(cfg *libhoney.Config, filename *string, ciProvider *string) *cobra.Command {
@@ -59,7 +60,19 @@ will be launched via "bash -c" using "exec".`,
  rand.Read(spanBytes)
 
  start := time.Now()
- err := runCommand(subcmd)
+
+ // copy out the current set of fields to avoid later modification
+ localFields := map[string]interface{}{}
+ for k, v := range ev.Fields() {
+ localFields[k] = v
+ }
+ var spanID = fmt.Sprintf("%x", spanBytes)
+ prop := &propagation.PropagationContext{
+ TraceID: traceID,
+ ParentID: spanID,
+ TraceContext: localFields,
+ }
+ err := runCommand(subcmd, prop)
  dur := time.Since(start)
 
  // Annotate with arbitrary fields after the command runs
@@ -68,7 +81,7 @@ will be launched via "bash -c" using "exec".`,
 
  ev.Add(map[string]interface{}{
  "trace.parent_id": stepID,
- "trace.span_id": fmt.Sprintf("%x", spanBytes),
+ "trace.span_id": spanID,
  "service_name": "cmd",
  "name": name,
  "duration_ms": dur / time.Millisecond,
@@ -91,10 +104,14 @@ will be launched via "bash -c" using "exec".`,
  return execCmd
 }
 
-func runCommand(subcmd string) error {
+func runCommand(subcmd string, prop *propagation.PropagationContext) error {
  fmt.Println("running /bin/bash -c", subcmd)
  cmd := exec.Command("/bin/bash", "-c", subcmd)
 
+ cmd.Env = append(os.Environ(),
+ "HONEYCOMB_TRACE=" + propagation.MarshalHoneycombTraceContext(prop),
+ )
+
  cmd.Stdout = os.Stdout
  cmd.Stderr = os.Stderr