feat: add OpenTelemetry support (#16)

This change adds support for tracing templating operations and function
calls using an OpenTelemetry tracer that is provided as an option to the
easytemplate engine.

engine.go

@@ -5,6 +5,7 @@
 package easytemplate
 
 import (
+ "context"
  "errors"
  "fmt"
  "io/fs"
@@ -15,6 +16,10 @@ import (
  "github.com/speakeasy-api/easytemplate/internal/template"
  "github.com/speakeasy-api/easytemplate/internal/utils"
  "github.com/speakeasy-api/easytemplate/internal/vm"
+ "go.opentelemetry.io/otel/attribute"
+ "go.opentelemetry.io/otel/codes"
+ "go.opentelemetry.io/otel/trace"
+ "go.opentelemetry.io/otel/trace/noop"
 )
 
 var (
@@ -33,7 +38,8 @@ var (
 // CallContext is the context that is passed to go functions when called from js.
 type CallContext struct {
  goja.FunctionCall
- VM *vm.VM
+ VM *vm.VM
+ Ctx context.Context //nolint:containedctx // runtime context is necessarily stored in a struct as it jumps from Go to JS.
 }
 
 // Opt is a function that configures the Engine.
@@ -93,6 +99,13 @@ func WithJSFiles(files map[string]string) Opt {
  }
 }
 
+// WithTracer attaches an OpenTelemetry tracer to the engine and enables tracing support.
+func WithTracer(t trace.Tracer) Opt {
+ return func(e *Engine) {
+ e.tracer = t
+ }
+}
+
 // WithDebug enables debug mode for the engine, which will log additional information when errors occur.
 func WithDebug() Opt {
  return func(e *Engine) {
@@ -110,6 +123,8 @@ type Engine struct {
  ran bool
  jsFuncs map[string]func(call CallContext) goja.Value
  jsFiles map[string]string
+
+ tracer trace.Tracer
 }
 
 // New creates a new Engine with the provided options.
@@ -148,12 +163,21 @@ func New(opts ...Opt) *Engine {
  opt(e)
  }
 
+ if e.tracer == nil {
+ e.tracer = noop.NewTracerProvider().Tracer("easytemplate")
+ }
+
  return e
 }
 
 // RunScript runs the provided script file, with the provided data, starting the template engine and templating any templates triggered from the script.
 func (e *Engine) RunScript(scriptFile string, data any) error {
- vm, err := e.init(data)
+ return e.RunScriptWithContext(context.Background(), scriptFile, data)
+}
+
+// RunScriptWithContext runs the provided script file, with the provided data, starting the template engine and templating any templates triggered from the script.
+func (e *Engine) RunScriptWithContext(ctx context.Context, scriptFile string, data any) error {
+ vm, err := e.init(ctx, data)
  if err != nil {
  return err
  }
@@ -172,7 +196,12 @@ func (e *Engine) RunScript(scriptFile string, data any) error {
 
 // RunMethod enables calls to global template methods from easytemplate.
 func (e *Engine) RunMethod(scriptFile string, data any, fnName string, args ...any) (goja.Value, error) {
- vm, err := e.init(data)
+ return e.RunMethodWithContext(context.Background(), scriptFile, data, fnName, args...)
+}
+
+// RunMethodWithContext enables calls to global template methods from easytemplate.
+func (e *Engine) RunMethodWithContext(ctx context.Context, scriptFile string, data any, fnName string, args ...any) (goja.Value, error) {
+ vm, err := e.init(ctx, data)
  if err != nil {
  return nil, err
  }
@@ -205,7 +234,12 @@ func (e *Engine) RunMethod(scriptFile string, data any, fnName string, args ...a
 
 // RunTemplate runs the provided template file, with the provided data, starting the template engine and templating the provided template to a file.
 func (e *Engine) RunTemplate(templateFile string, outFile string, data any) error {
- vm, err := e.init(data)
+ return e.RunTemplateWithContext(context.Background(), templateFile, outFile, data)
+}
+
+// RunTemplateWithContext runs the provided template file, with the provided data, starting the template engine and templating the provided template to a file.
+func (e *Engine) RunTemplateWithContext(ctx context.Context, templateFile string, outFile string, data any) error {
+ vm, err := e.init(ctx, data)
  if err != nil {
  return err
  }
@@ -215,7 +249,12 @@ func (e *Engine) RunTemplate(templateFile string, outFile string, data any) erro
 
 // RunTemplateString runs the provided template file, with the provided data, starting the template engine and templating the provided template, returning the rendered result.
 func (e *Engine) RunTemplateString(templateFile string, data any) (string, error) {
- vm, err := e.init(data)
+ return e.RunTemplateStringWithContext(context.Background(), templateFile, data)
+}
+
+// RunTemplateStringWithContext runs the provided template file, with the provided data, starting the template engine and templating the provided template, returning the rendered result.
+func (e *Engine) RunTemplateStringWithContext(ctx context.Context, templateFile string, data any) (string, error) {
+ vm, err := e.init(ctx, data)
  if err != nil {
  return "", err
  }
@@ -225,7 +264,12 @@ func (e *Engine) RunTemplateString(templateFile string, data any) (string, error
 
 // RunTemplateStringInput runs the provided input template string, with the provided data, starting the template engine and templating the provided template, returning the rendered result.
 func (e *Engine) RunTemplateStringInput(name, template string, data any) (string, error) {
- vm, err := e.init(data)
+ return e.RunTemplateStringInputWithContext(context.Background(), name, template, data)
+}
+
+// RunTemplateStringInputWithContext runs the provided input template string, with the provided data, starting the template engine and templating the provided template, returning the rendered result.
+func (e *Engine) RunTemplateStringInputWithContext(ctx context.Context, name, template string, data any) (string, error) {
+ vm, err := e.init(ctx, data)
  if err != nil {
  return "", err
  }
@@ -234,7 +278,7 @@ func (e *Engine) RunTemplateStringInput(name, template string, data any) (string
 }
 
 //nolint:funlen
-func (e *Engine) init(data any) (*vm.VM, error) {
+func (e *Engine) init(ctx context.Context, data any) (*vm.VM, error) {
  if e.ran {
  return nil, ErrAlreadyRan
  }
@@ -258,6 +302,7 @@ func (e *Engine) init(data any) (*vm.VM, error) {
  return fn(CallContext{
  FunctionCall: call,
  VM: v,
+ Ctx: ctx,
  })
  }
  }(fn)
@@ -270,7 +315,20 @@ func (e *Engine) init(data any) (*vm.VM, error) {
  // This need to have the vm passed in so that the functions can be called
  e.templator.TmplFuncs["templateFile"] = func(v *vm.VM) func(string, string, any) (string, error) {
  return func(templateFile, outFile string, data any) (string, error) {
- err := e.templator.TemplateFile(v, templateFile, outFile, data)
+ var err error
+ _, span := e.tracer.Start(ctx, "templateFile", trace.WithAttributes(
+ attribute.String("templateFile", templateFile),
+ attribute.String("outFile", outFile),
+ ))
+ defer func() {
+ span.RecordError(err)
+ if err != nil {
+ span.SetStatus(codes.Error, err.Error())
+ }
+ span.End()
+ }()
+
+ err = e.templator.TemplateFile(v, templateFile, outFile, data)
  if err != nil {
  return "", err
  }

go.mod

@@ -8,7 +8,9 @@ require (
  github.com/evanw/esbuild v0.19.11
  github.com/go-sourcemap/sourcemap v2.1.3+incompatible
  github.com/golang/mock v1.6.0
- github.com/stretchr/testify v1.8.1
+ github.com/stretchr/testify v1.8.4
+ go.opentelemetry.io/otel v1.24.0
+ go.opentelemetry.io/otel/trace v1.24.0
 )
 
 require (

go.sum

@@ -2,7 +2,6 @@ github.com/chzyer/logex v1.2.0/go.mod h1:9+9sk7u7pGNWYMkh0hdiL++6OeibzJccyQU4p4M
 github.com/chzyer/readline v1.5.0/go.mod h1:x22KAscuvRqlLoK9CsoYsmxoXZMMFVyOl86cAH8qUic=
 github.com/chzyer/test v0.0.0-20210722231415-061457976a23/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dlclark/regexp2 v1.4.1-0.20201116162257-a2a8dda75c91/go.mod h1:2pZnwuY/m+8K6iRw6wQdMtk+rH5tNGR1i55kozfMjCc=
@@ -22,6 +21,7 @@ github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyL
 github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg=
 github.com/golang/mock v1.6.0 h1:ErTB+efbowRARo13NNdxyJji2egdxLGQhRaY+DUumQc=
 github.com/golang/mock v1.6.0/go.mod h1:p6yTPP+5HYm5mzsMV8JkE6ZKdX+/wYM6Hr+LicevLPs=
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/pprof v0.0.0-20230207041349-798e818bf904/go.mod h1:uglQLonpP8qtYCYyzA+8c/9qtqgA3qsXGYqCPKARAFg=
 github.com/google/pprof v0.0.0-20240117000934-35fc243c5815 h1:WzfWbQz/Ze8v6l++GGbGNFZnUShVpP/0xffCPLL+ax8=
 github.com/google/pprof v0.0.0-20240117000934-35fc243c5815/go.mod h1:czg5+yv1E0ZGTi6S6vVK1mke0fV+FaUhNGcd6VRS9Ik=
@@ -38,15 +38,14 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.6.1 h1:/FiVV8dS/e+YqF2JvO3yXRFbBLTIuSDkuC7aBOAvL+k=
 github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
-github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
-github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
-github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
-github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+go.opentelemetry.io/otel v1.24.0 h1:0LAOdjNmQeSTzGBzduGe/rU4tZhMwL5rWgtp9Ku5Jfo=
+go.opentelemetry.io/otel v1.24.0/go.mod h1:W7b9Ozg4nkF5tWI5zsXkaKKDjdVjpD4oAt9Qi/MArHo=
+go.opentelemetry.io/otel/trace v1.24.0 h1:CsKnnL4dUAr/0llH9FKuc698G04IrpWV0MQA/Y1YELI=
+go.opentelemetry.io/otel/trace v1.24.0/go.mod h1:HPc3Xr/cOApsBI154IU0OI0HJexz+aw5uPdbs3UCjNU=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
@@ -95,6 +94,5 @@ gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EV
 gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
-gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

templating.go

@@ -2,34 +2,73 @@ package easytemplate
 
 import (
  "github.com/dop251/goja"
+ "go.opentelemetry.io/otel/attribute"
+ "go.opentelemetry.io/otel/codes"
+ "go.opentelemetry.io/otel/trace"
 )
 
 func (e *Engine) templateFileJS(call CallContext) goja.Value {
+ templateFile := call.Argument(0).String()
+ outFile := call.Argument(1).String()
  inputData := call.Argument(2).Export() //nolint:gomnd
 
- if err := e.templator.TemplateFile(call.VM, call.Argument(0).String(), call.Argument(1).String(), inputData); err != nil {
+ ctx := call.Ctx
+ _, span := e.tracer.Start(ctx, "js:templateFile", trace.WithAttributes(
+ attribute.String("templateFile", templateFile),
+ attribute.String("outFile", outFile),
+ ))
+ defer span.End()
+
+ if err := e.templator.TemplateFile(call.VM, templateFile, outFile, inputData); err != nil {
+ span.RecordError(err)
+ span.SetStatus(codes.Error, err.Error())
+ span.End()
+
  panic(call.VM.NewGoError(err))
  }
 
  return goja.Undefined()
 }
 
 func (e *Engine) templateStringJS(call CallContext) goja.Value {
+ templateFile := call.Argument(0).String()
  inputData := call.Argument(1).Export()
 
- output, err := e.templator.TemplateString(call.VM, call.Argument(0).String(), inputData)
+ ctx := call.Ctx
+ _, span := e.tracer.Start(ctx, "js:templateString", trace.WithAttributes(
+ attribute.String("templateFile", templateFile),
+ ))
+ defer span.End()
+
+ output, err := e.templator.TemplateString(call.VM, templateFile, inputData)
  if err != nil {
+ span.RecordError(err)
+ span.SetStatus(codes.Error, err.Error())
+ span.End()
+
  panic(call.VM.NewGoError(err))
  }
 
  return call.VM.ToValue(output)
 }
 
 func (e *Engine) templateStringInputJS(call CallContext) goja.Value {
+ name := call.Argument(0).String()
+ input := call.Argument(1).String()
  inputData := call.Argument(2).Export() //nolint:gomnd
 
- output, err := e.templator.TemplateStringInput(call.VM, call.Argument(0).String(), call.Argument(1).String(), inputData)
+ ctx := call.Ctx
+ _, span := e.tracer.Start(ctx, "js:templateStringInput", trace.WithAttributes(
+ attribute.String("name", name),
+ ))
+ defer span.End()
+
+ output, err := e.templator.TemplateStringInput(call.VM, name, input, inputData)
  if err != nil {
+ span.RecordError(err)
+ span.SetStatus(codes.Error, err.Error())
+ span.End()
+
  panic(call.VM.NewGoError(err))
  }