appsec: add comments for new SDK body related code

appsec/appsec.go

@@ -16,6 +16,9 @@ import (
 	"gopkg.in/DataDog/dd-trace-go.v1/internal/appsec/dyngo/instrumentation/httpsec"
 )
 
+// MonitorParsedBody is an SDK solution for users to ask AppSec to perform rule matching on the parsed request body.
+// `body`: the parsed body value to be used for rule matching.
+// `ctx`: the context of the http.Request that for which the matching is to be performed.
 func MonitorParsedBody(ctx context.Context, body interface{}) {
 	if appsec.Enabled() {
 		if span, ok := tracer.SpanFromContext(ctx); ok {

internal/appsec/dyngo/instrumentation/httpsec/http.go

@@ -51,6 +51,10 @@ type (
 	}
 )
 
+// map used to keep track of ongoing operations per span. This is used as a
+// means to keep track of parent operations when creating new operations.
+// An example where this comes in handy is when users use an SDK function to
+// instrument a specific address which results in a new operation start/finish.
 var spanOpMap = make(map[ddtrace.Span]dyngo.Operation)
 
 func MonitorParsedBody(span ddtrace.Span, body interface{}) {
@@ -129,18 +133,18 @@ type (
 )
 
 // StartOperation starts an HTTP handler operation, along with the given
-// arguments and parent operation, and emits a start event up in the
-// operation stack. When parent is nil, the operation is linked to the global
-// root operation.
+// arguments and current span, emits a start event up in the operation stack
+// and update the span operation map.
+// When parent is nil, the operation is linked to the global root operation.
 func StartOperation(args HandlerOperationArgs, span ddtrace.Span) *Operation {
 	op := &Operation{Operation: dyngo.NewOperation(spanOpMap[span])}
 	spanOpMap[span] = op
 	dyngo.StartOperation(op, args)
 	return op
 }
 
-// Finish the HTTP handler operation, along with the given results, and emits a
-// finish event up in the operation stack.
+// Finish the HTTP handler operation, along with the given results, emits a
+// finish event up in the operation stack and update the span operation map.
 func (op *Operation) Finish(res HandlerOperationRes, span ddtrace.Span) json.RawMessage {
 	dyngo.FinishOperation(op, res)
 	if parent := op.Parent(); parent != nil {
@@ -151,15 +155,17 @@ func (op *Operation) Finish(res HandlerOperationRes, span ddtrace.Span) json.Raw
 	return op.events
 }
 
-// WIP
+// StartSDKBodyOperation starts the SDKBody operation, emits a start event and
+// update the span operation map.
 func StartSDKBodyOperation(args SDKBodyOperationArgs, span ddtrace.Span) *SDKBodyOperation {
 	op := &SDKBodyOperation{Operation: dyngo.NewOperation(spanOpMap[span])}
 	spanOpMap[span] = op
 	dyngo.StartOperation(op, args)
 	return op
 }
 
-// WIP
+// Finish the SDKBody operation, emits a finish event and update the span
+// operation map
 func (op *SDKBodyOperation) Finish(span ddtrace.Span) json.RawMessage {
 	dyngo.FinishOperation(op, SDKBodyOperationRes{})
 	spanOpMap[span] = op.Parent()