Merge pull request #9 from equinix-labs/document-init-dependency

document dependency on otel state & envvars for local collector

README.md

@@ -5,11 +5,10 @@ and aims for a small code footprint and gets its configuration from environment
 variables exclusively. The intent is to be able to drop this into existing
 codebases with minimal code churn.
 
-TODO:
-- [x] bootstrap egressing traces to a collector
-- [ ] figure out how to test envvar mixes (otel-cli server json)
-- [ ] metrics support?
-- [ ] logs support?
+There is also an otelhelpers package in `github.com/equinix-labs/otel-init-go/otelinit`
+to help with traceparent propagation. The propagation helpers depend on OTel
+`otel.SetTextMapPropagator()` having been called. `otelinit.InitOpenTelemetry`
+does this for you.
 
 ## API
 
@@ -36,6 +35,14 @@ If `OTEL_EXPORTER_OTLP_ENDPOINT` is unset or empty, the init code will
 do almost nothing, so it's as safe as possible to add this to a service,
 deploy it, and configure it later.
 
+To send traces to a localhost OTLP server without encryption, you will need to
+set both OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_INSECURE.
+
+```sh
+export OTEL_EXPORTER_OTLP_ENDPOINT="localhost:4317"
+export OTEL_EXPORTER_OTLP_INSECURE=true
+```
+
 TODO:
 - [ ] add config for TLS auth
 

otelhelpers/context_traceparent.go

@@ -15,6 +15,7 @@ import (
 // environment variable and if it's set, it grabs the traceparent and
 // adds it to the context it returns. When there is no envvar or it's
 // empty, the original context is returned unmodified.
+// Depends on global OTel TextMapPropagator.
 func ContextWithEnvTraceparent(ctx context.Context) context.Context {
 	traceparent := os.Getenv("TRACEPARENT")
 	if traceparent != "" {
@@ -28,6 +29,7 @@ func ContextWithEnvTraceparent(ctx context.Context) context.Context {
 // if it's there. Does no validation. Returns the original context if there is
 // no cmdline option or if there's an error doing the read.
 // This is Linux-only but should be safe on other operating systems.
+// Depends on global OTel TextMapPropagator.
 func ContextWithCmdlineTraceparent(ctx context.Context) context.Context {
 	tp, err := tpFromCmdline("/proc/cmdline")
 	if err != nil {
@@ -42,13 +44,15 @@ func ContextWithCmdlineTraceparent(ctx context.Context) context.Context {
 // then /proc/cmdline and returns a context with them set, if available. When
 // both are present, the cmdline is prioritized. When neither is present,
 // the original context is returned as-is.
+// Depends on global OTel TextMapPropagator.
 func ContextWithCmdlineOrEnvTraceparent(ctx context.Context) context.Context {
 	ctx = ContextWithEnvTraceparent(ctx)
 	return ContextWithCmdlineTraceparent(ctx)
 }
 
 // ContextWithTraceparentString takes a W3C traceparent string, uses the otel
 // carrier code to get it into a context it returns ready to go.
+// Depends on global OTel TextMapPropagator.
 func ContextWithTraceparentString(ctx context.Context, traceparent string) context.Context {
 	carrier := SimpleCarrier{}
 	carrier.Set("traceparent", traceparent)
@@ -57,7 +61,7 @@ func ContextWithTraceparentString(ctx context.Context, traceparent string) conte
 }
 
 // TraceparentStringFromContext gets the current trace from the context and
-// returns a W3C traceparent string.
+// returns a W3C traceparent string. Depends on global OTel TextMapPropagator.
 func TraceparentStringFromContext(ctx context.Context) string {
 	carrier := SimpleCarrier{}
 	prop := otel.GetTextMapPropagator()