Improve handling of status code/message (#51) (#70)

Improved how translators handling mapping status codes and messages to and from OC

translator/trace/README.md documents the new behaviour

processor/tracesamplerprocessor/tracesamplerprocessor.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

processor/tracesamplerprocessor/tracesamplerprocessor_test.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/jaegerreceiver/jaeger_agent_test.go

@@ -171,12 +171,6 @@ func testJaegerAgent(t *testing.T, agentEndpoint string, receiverConfig *Configu
 					},
 					Attributes: &tracepb.Span_Attributes{
 						AttributeMap: map[string]*tracepb.AttributeValue{
-							"status.code": {
-								Value: &tracepb.AttributeValue_IntValue{IntValue: trace.StatusCodeNotFound},
-							},
-							"status.message": {
-								Value: &tracepb.AttributeValue_StringValue{StringValue: &tracepb.TruncatableString{Value: "Stale indices"}},
-							},
 							"error": {
 								Value: &tracepb.AttributeValue_BoolValue{BoolValue: true},
 							},
@@ -204,12 +198,6 @@ func testJaegerAgent(t *testing.T, agentEndpoint string, receiverConfig *Configu
 					},
 					Attributes: &tracepb.Span_Attributes{
 						AttributeMap: map[string]*tracepb.AttributeValue{
-							"status.code": {
-								Value: &tracepb.AttributeValue_IntValue{IntValue: trace.StatusCodeInternal},
-							},
-							"status.message": {
-								Value: &tracepb.AttributeValue_StringValue{StringValue: &tracepb.TruncatableString{Value: "Frontend crash"}},
-							},
 							"error": {
 								Value: &tracepb.AttributeValue_BoolValue{BoolValue: true},
 							},

receiver/jaegerreceiver/trace_receiver_test.go

@@ -154,12 +154,6 @@ func TestReception(t *testing.T) {
 					},
 					Attributes: &tracepb.Span_Attributes{
 						AttributeMap: map[string]*tracepb.AttributeValue{
-							"status.code": {
-								Value: &tracepb.AttributeValue_IntValue{IntValue: trace.StatusCodeNotFound},
-							},
-							"status.message": {
-								Value: &tracepb.AttributeValue_StringValue{StringValue: &tracepb.TruncatableString{Value: "Stale indices"}},
-							},
 							"error": {
 								Value: &tracepb.AttributeValue_BoolValue{BoolValue: true},
 							},
@@ -187,12 +181,6 @@ func TestReception(t *testing.T) {
 					},
 					Attributes: &tracepb.Span_Attributes{
 						AttributeMap: map[string]*tracepb.AttributeValue{
-							"status.code": {
-								Value: &tracepb.AttributeValue_IntValue{IntValue: trace.StatusCodeInternal},
-							},
-							"status.message": {
-								Value: &tracepb.AttributeValue_StringValue{StringValue: &tracepb.TruncatableString{Value: "Frontend crash"}},
-							},
 							"error": {
 								Value: &tracepb.AttributeValue_BoolValue{BoolValue: true},
 							},

receiver/prometheusreceiver/config.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/prometheusreceiver/config_test.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/prometheusreceiver/factory.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/prometheusreceiver/factory_test.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/zipkinreceiver/config.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/zipkinreceiver/config_test.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/zipkinreceiver/factory.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

receiver/zipkinreceiver/factory_test.go

@@ -1,4 +1,4 @@
-// Copyright 2019, OpenCensus Authors
+// Copyright 2019, OpenTelemetry Authors
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.

translator/trace/README.md

@@ -0,0 +1,74 @@
+# Overview
+
+This package implements a number of translators that help translate spans to and from OpenCensus format to a number of other supported formats such as Jaeger Proto, Jaeger Thrift, Zipkin Thrift, Zipkin JSON. This document mentions how certain non-obvious things should be handled.
+
+## Links:
+
+* [OpenTracing Semantic Conventions](https://github.com/opentracing/specification/blob/master/semantic_conventions.md)
+
+## Status Codes and Messages
+
+### OpenCensus
+
+OpenCensus protocol has a special field to represent the status of an operation. The status field has two fields, an int32 field called `code` and a string field called `message`. When converting from other formats, status field must be set from the relevant tags/attributes of the source format. When converting from OC to other formats, the status field must be translated to appropriate tags/attributes of the target format. 
+
+
+### Jaeger to OC
+
+Jaeger spans may contain two possible sets of tags that can possibly represent the status of an operation:
+
+- `status.code` and `status.message`
+- `http.status_code` and `http.status_message`
+
+When converting from Jaeger to OC, 
+
+1. OC status should be set from `status.code` and `status.message` tags if `status.code` tag is found on the Jaeger span. Since OC already has a special status field, these tags (`status.code` and `status.message`) are redundant and should be dropped from resultant OC span.
+2. If the `status.code` tag is not present, status should be set from `http.status_code` and `http.status_message` if the `http.status_code` tag is found. HTTP status code should be mapped to the appropriate gRPC status code before using it in OC status. These tags should be preserved and added to the resultant OC span as attributes.
+3. If none of the tags are found, OC status should not be set.
+
+
+### Zipkin to OC
+
+In addition to the two sets of tags mentioned in the previous section, Zipkin spans can possibly contain a third set of tags to represent operation status resulting in the following sets of tags:
+
+- `census.status_code` and `census.status_description`
+- `status.code` and `status.message`
+- `http.status_code` and `http.status_message`
+
+When converting from Zipkin to OC,
+
+1. OC status should be set from `census.status_code` and `census.status_description` if `census.status_code` tag is found on the Zipkin span. These tags should be dropped from the resultant OC span.
+2. If the `census.status_code` tag is not found in step 1, OC status should be set from `status.code` and `status.message` tags if the `status.code` tag is present. The tags should be dropped from the resultant OC span.
+3. If no tags are found in step 1 and 2, OC status should be set from `http.status_code` and `http.status_message` if either `http.status_code` tag is found. These tags should be preserved and added to the resultant OC span as attributes.
+4. If none of the tags are found, OC status should not be set.
+
+
+Note that codes and messages from different sets of tags should not be mixed to form the status field. For example, OC status should not contain code from `http.status_code` but message from `status.message` and vice-versa. Both fields must be set from the same set of tags even if it means leaving one of the two fields empty.
+
+
+### OC to Jaeger
+
+When converting from OC to Jaeger, if the OC span has a status field set, then
+
+* `code` should be added as a `status.code` tag.
+* `message` should be added as a `status.message` tag.
+
+### OC to Zipkin
+
+When converting from OC to Zipkin, if the OC span has the status field set, then
+
+* `code` should be added as a `census.status_code` tag.
+* `message` should be added as a `census.status_description` tag.
+
+In addition to this, if the OC status field represents a non-OK status, then a tag with the key `error` should be added and set to the same value as that of the status message falling back to status code when status message is not available.
+
+### Note:
+
+If either target tags (`status.*` or `census.status_*`) are already present on the span, then they should be preserved and not overwritten from the status field. This is extremely unlikely to happen within the collector because of how things are implemented but any other implementations should still follow this rule.
+
+
+## Converting HTTP status codes to OC codes
+
+The following guidelines should be followed for translating HTTP status codes to OC ones. https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
+
+This is implemented by the `tracetranslator` package as `HTTPToOCCodeMapper`.

translator/trace/grpc_http_mapper.go

@@ -0,0 +1,61 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tracetranslator
+
+// https://github.com/googleapis/googleapis/blob/bee79fbe03254a35db125dc6d2f1e9b752b390fe/google/rpc/code.proto#L33-L186
+const (
+	OCOK                 = 0
+	OCCancelled          = 1
+	OCUnknown            = 2
+	OCInvalidArgument    = 3
+	OCDeadlineExceeded   = 4
+	OCNotFound           = 5
+	OCAlreadyExists      = 6
+	OCPermissionDenied   = 7
+	OCResourceExhausted  = 8
+	OCFailedPrecondition = 9
+	OCAborted            = 10
+	OCOutOfRange         = 11
+	OCUnimplemented      = 12
+	OCInternal           = 13
+	OCUnavailable        = 14
+	OCDataLoss           = 15
+	OCUnauthenticated    = 16
+)
+
+var httpToOCCodeMap = map[int32]int32{
+	400: OCInvalidArgument,
+	401: OCUnauthenticated,
+	403: OCPermissionDenied,
+	404: OCNotFound,
+	409: OCAborted,
+	429: OCResourceExhausted,
+	499: OCCancelled,
+	500: OCInternal,
+	501: OCUnimplemented,
+	503: OCUnavailable,
+	504: OCDeadlineExceeded,
+}
+
+// OCStatusCodeFromHTTP takes an HTTP status code and return the appropriate OC status code
+func OCStatusCodeFromHTTP(code int32) int32 {
+	if code >= 200 && code < 300 {
+		return OCOK
+	}
+	if code, ok := httpToOCCodeMap[code]; ok {
+		return code
+	}
+	return OCUnknown
+}

translator/trace/jaeger/jaegerthrift_to_protospan.go

@@ -190,6 +190,8 @@ func jtagsToAttributes(tags []*jaeger.Tag) (string, tracepb.Span_SpanKind, *trac
 
 	var statusCodePtr *int32
 	var statusMessage string
+	var httpStatusCodePtr *int32
+	var httpStatusMessage string
 	var message string
 
 	sAttribs := make(map[string]*tracepb.AttributeValue)
@@ -206,12 +208,19 @@ func jtagsToAttributes(tags []*jaeger.Tag) (string, tracepb.Span_SpanKind, *trac
 				sKind = tracepb.Span_SERVER
 			}
 
-		case "http.status_code", "status.code": // It is expected to be an int
-			statusCodePtr = new(int32)
-			*statusCodePtr = int32(tag.GetVLong())
+		case tracetranslator.TagStatusCode:
+			statusCodePtr = statusCodeFromTag(tag)
+			continue
 
-		case "http.status_message", "status.message":
+		case tracetranslator.TagStatusMsg:
 			statusMessage = tag.GetVStr()
+			continue
+
+		case tracetranslator.TagHTTPStatusCode:
+			httpStatusCodePtr = statusCodeFromHTTPTag(tag)
+
+		case tracetranslator.TagHTTPStatusMsg:
+			httpStatusMessage = tag.GetVStr()
 
 		case "message":
 			message = tag.GetVStr()
@@ -248,6 +257,11 @@ func jtagsToAttributes(tags []*jaeger.Tag) (string, tracepb.Span_SpanKind, *trac
 		sAttribs[tag.Key] = attrib
 	}
 
+	if statusCodePtr == nil {
+		statusCodePtr = httpStatusCodePtr
+		statusMessage = httpStatusMessage
+	}
+
 	var sStatus *tracepb.Status
 	if statusCodePtr != nil || statusMessage != "" {
 		statusCode := int32(0)