enhance: docs links and flag clarification

tracing/flags.go

@@ -12,27 +12,27 @@ var Flags = []cli.Flag{
 	&cli.BoolFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_ENABLE"},
 		Name:    "tracing.enable",
-		Usage:   "enable otel tracing",
+		Usage:   "enable otel tracing. see: https://opentelemetry.io/docs/concepts/signals/traces/",
 		Value:   false,
 	},
-
-	// Exporter Flags
-
 	&cli.StringFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_SERVICE_NAME"},
 		Name:    "tracing.service.name",
-		Usage:   "set otel tracing service name",
+		Usage:   "set otel tracing service name. see: https://opentelemetry.io/docs/languages/sdk-configuration/general/",
 		Value:   "vela-server",
 	},
+
+	// Exporter Flags
+
 	&cli.StringFlag{
 		EnvVars: []string{"VELA_OTEL_EXPORTER_OTLP_ENDPOINT"},
 		Name:    "tracing.exporter.endpoint",
-		Usage:   "set the otel exporter endpoint (ex. scheme://host:port)",
+		Usage:   "set the otel exporter endpoint (ex. scheme://host:port). see: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/",
 	},
 	&cli.StringFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_EXPORTER_SSL_CERT_PATH"},
 		Name:    "tracing.exporter.cert_path",
-		Usage:   "set the path to certs used for communicating with the otel exporter. if not set, will use insecure communication",
+		Usage:   "set the path to certs used for communicating with the otel exporter. if not set, will use insecure communication. see: https://opentelemetry.io/docs/specs/otel/protocol/exporter/",
 	},
 	&cli.StringFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_TLS_MIN_VERSION"},
@@ -41,28 +41,28 @@ var Flags = []cli.Flag{
 		Value:   "1.2",
 	},
 
-	// Resource Flags
+	// Attribute Flags
 
 	&cli.StringSliceFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_RESOURCE_ATTRIBUTES"},
 		Name:    "tracing.resource.attributes",
-		Usage:   "set otel resource attributes as a list of key=value pairs. each one will be attached to each span as a resource attribute",
+		Usage:   "set otel resource attributes as a list of key=value pairs. each one will be attached to each span as a 'process' attribute. see: https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes",
 		Value:   cli.NewStringSlice("process.runtime.name=go"),
 	},
 	&cli.StringSliceFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_RESOURCE_ENV_ATTRIBUTES"},
 		Name:    "tracing.resource.env_attributes",
-		Usage:   "set otel resource attributes as a list of key=env_variable_key pairs. each one will be attached to each span as an attribute where the value is retrieved from the environment using the pair value",
+		Usage:   "set otel resource attributes as a list of key=env_variable_key pairs. each one will be attached to each span as a 'process' attribute where the value is retrieved from the environment using the pair value. see: https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes",
 	},
 	&cli.StringSliceFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_SPAN_ATTRIBUTES"},
 		Name:    "tracing.span.attributes",
-		Usage:   "set otel span attributes as a list of key=value pairs. each one will be attached to each span as a sampler attribute",
+		Usage:   "set otel span attributes as a list of key=value pairs. each one will be attached to each span as a 'tag' attribute. see: https://opentelemetry.io/docs/languages/go/instrumentation/#span-attributes",
 	},
 	&cli.StringSliceFlag{
 		EnvVars: []string{"VELA_OTEL_TRACING_TRACESTATE_ATTRIBUTES"},
 		Name:    "tracing.tracestate.attributes",
-		Usage:   "set otel tracestate attributes as a list of key=value pairs. each one will be inserted into the tracestate for each sampled span",
+		Usage:   "set otel tracestate attributes as a list of key=value pairs. each one will be inserted into the tracestate for each sampled span. see: https://www.w3.org/TR/trace-context",
 	},
 
 	// Sampler Flags