add comments

Co-authored-by: Pieter Noordhuis <pieter.noordhuis@databricks.com>

libs/telemetry/api.go

@@ -2,9 +2,20 @@ package telemetry
 
 // RequestBody is the request body type bindings for the /telemetry-ext API endpoint.
 type RequestBody struct {
-	UploadTime int64    `json:"uploadTime"`
-	Items      []string `json:"items"`
-	ProtoLogs  []string `json:"protoLogs"`
+	UploadTime int64 `json:"uploadTime"`
+
+	// DO NOT USE. This is the legacy field for logging in usage logs (not lumberjack).
+	// We keep this around because the API endpoint works only if this field is serialized
+	// to an empty array.
+	Items []string `json:"items"`
+
+	// JSON encoded strings containing the proto logs. Since it's represented as a
+	// string here, the values here end up being double JSON encoded in the final
+	// request body.
+	//
+	// Any logs here will be logged in our lumberjack tables as long as a corresponding
+	// protobuf is defined in universe.
+	ProtoLogs []string `json:"protoLogs"`
 }
 
 // ResponseBody is the response body type bindings for the /telemetry-ext API endpoint.
@@ -15,5 +26,5 @@ type ResponseBody struct {
 
 type LogError struct {
 	Message   string `json:"message"`
-	ErrorType string `json:"ErrorType"`
+	ErrorType string `json:"errorType"`
 }

libs/telemetry/protos/bundle_deploy.go

@@ -33,7 +33,7 @@ type BundleDeployEvent struct {
 // are no guarantees for these metrics and they maybe removed in the future without
 // any notice.
 type BundleDeployExperimental struct {
-	// Number of YAML (or JSON) configuration files in the bundle.
+	// Number of configuration files in the bundle.
 	ConfigurationFileCount int64 `json:"configuration_file_count,omitempty"`
 
 	// Size in bytes of the Terraform state file