@@ -18,6 +18,15 @@ Task before the fork is kept, unchanged, at the bottom of this file.
   `mcp:` task key hides tasks or sets tool hints (`read_only`, `destructive`,
   `idempotent`). Implements the long-standing upstream request
   go-task/task#2324.
+- Added `--profile <file>`, which writes a timeline of the run in the Chrome
+  trace format (for ui.perfetto.dev) and prints the critical path and the
+  slowest tasks.
+- Added OpenTelemetry tracing: when `OTEL_EXPORTER_OTLP_ENDPOINT` (or the
+  traces-specific variable) is set, spans for the run, each task, dependency
+  waits, up-to-date checks and each command are exported over OTLP
+  (http/protobuf or grpc). An incoming `TRACEPARENT` is used as the parent,
+  and commands get `TRACEPARENT` so tools they run can join the trace.
+  Implements the upstream feature request go-task/task#2948.
 - Added `--affected` (with optional `--since <ref>`) to run only the given
   tasks that are affected by changes in git, or, with no task names, to list
   the affected tasks (`--json` for CI). A task is affected when a changed file
 
@@ -18,6 +18,7 @@ safe, well-described tools, and monorepos where CI time matters.
 | [`--graph`](docs/graph-and-explain.md#--graph-see-what-runs-what) | Prints the task graph as a tree, Mermaid, Graphviz DOT or JSON, and flags missing tasks and cycles. |
 | [`--explain`](docs/graph-and-explain.md#--explain-why-will-this-run) | Says whether each task would run and why, down to which source files were added, modified or removed. Add `--json` for machine-readable output. |
 | [`--affected`](docs/affected.md) | Runs only the tasks affected by what changed in git (`--since origin/main` for pull requests), following sources, Taskfile edits and the dependency graph. With no task names, lists them, optionally as JSON for CI. |
+| [`--profile` and OpenTelemetry](docs/tracing.md) | `--profile trace.json` writes a Perfetto/Chrome timeline and prints the critical path and slowest tasks. Setting `OTEL_EXPORTER_OTLP_ENDPOINT` exports spans for every task and command to any OpenTelemetry backend, with `TRACEPARENT` passed through to commands. |
 | [Cycle detection](docs/graph-and-explain.md#cycle-detection) | Stops at the first cyclic call and names it (`a -> b -> a`), instead of failing after 1,000 calls or hanging. |
 
 ## Install
 
@@ -144,6 +144,8 @@ tasks:
     desc: Runs test suite with signals and watch tests included
     deps: [sleepit:build, gotestsum:install]
     cmds:
+      # The signals tests run the taskgraph binary from bin/.
+      - go build -o {{.BIN}}/taskgraph{{exeExt}} ./cmd/taskgraph
       - gotestsum -f '{{.GOTESTSUM_FORMAT}}' -tags 'signals watch' ./...
 
   goreleaser:test:
 
@@ -10,8 +10,10 @@ import (
 	"strconv"
 	"strings"
 	"syscall"
+	"time"
 
 	"github.com/spf13/pflag"
+	"go.opentelemetry.io/otel/trace"
 
 	task "github.com/XXXDelirious/taskgraph"
 	"github.com/XXXDelirious/taskgraph/args"
@@ -20,6 +22,7 @@ import (
 	"github.com/XXXDelirious/taskgraph/internal/filepathext"
 	"github.com/XXXDelirious/taskgraph/internal/flags"
 	"github.com/XXXDelirious/taskgraph/internal/logger"
+	"github.com/XXXDelirious/taskgraph/internal/tracing"
 	"github.com/XXXDelirious/taskgraph/internal/version"
 	"github.com/XXXDelirious/taskgraph/mcpserver"
 	"github.com/XXXDelirious/taskgraph/taskfile/ast"
@@ -135,9 +138,13 @@ func run() error {
 		return runMCPServer()
 	}
 
+	tracer, shutdownTracing := setupTracing(log)
+	defer shutdownTracing()
+
 	e := task.NewExecutor(
 		flags.WithFlags(),
 		task.WithVersionCheck(true),
+		task.WithTracer(tracer),
 	)
 	if err := e.Setup(); err != nil {
 		return err
@@ -247,7 +254,83 @@ func run() error {
 		return e.Status(ctx, calls...)
 	}
 
-	return e.Run(ctx, calls...)
+	return runTraced(ctx, e, tracer, log, calls)
+}
+
+// setupTracing creates a tracer when --profile is set or the OpenTelemetry
+// environment variables ask for traces. Tracing is off in watch mode, where
+// runs never end. The returned function flushes exported spans.
+func setupTracing(log *logger.Logger) (*tracing.Tracer, func()) {
+	noop := func() {}
+	if flags.Watch || (flags.Profile == "" && !tracing.OTelEnabled()) {
+		return nil, noop
+	}
+
+	shutdown := noop
+	var otelTracer trace.Tracer
+	if tracing.OTelEnabled() {
+		t, shutdownOTel, err := tracing.SetupOTel(context.Background(), version.GetVersion())
+		if err != nil {
+			log.Warnf("task: OpenTelemetry tracing disabled: %v\n", err)
+		} else {
+			otelTracer = t
+			shutdown = func() {
+				ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer cancel()
+				if err := shutdownOTel(ctx); err != nil {
+					log.Warnf("task: could not export OpenTelemetry traces: %v\n", err)
+				}
+			}
+		}
+	}
+	return tracing.New(flags.Profile != "", otelTracer), shutdown
+}
+
+// runTraced runs the calls inside a root span, then writes the profile if
+// one was asked for.
+func runTraced(ctx context.Context, e *task.Executor, tracer *tracing.Tracer, log *logger.Logger, calls []*task.Call) error {
+	if tracer == nil {
+		return e.Run(ctx, calls...)
+	}
+
+	names := make([]string, 0, len(calls))
+	for _, c := range calls {
+		names = append(names, c.Task)
+	}
+	// Join the caller's trace when one is passed in, e.g. from CI.
+	ctx = tracing.ContextWithTraceParent(ctx, os.Getenv("TRACEPARENT"))
+	ctx, root := tracer.Start(ctx, tracing.KindRun, "taskgraph "+strings.Join(names, " "))
+	err := e.Run(ctx, calls...)
+	root.Finish(err)
+
+	if flags.Profile != "" {
+		if perr := writeProfile(flags.Profile, tracer.Spans(), log); perr != nil {
+			log.Warnf("task: could not write profile: %v\n", perr)
+		}
+	}
+	return err
+}
+
+func writeProfile(path string, spans []*tracing.Span, log *logger.Logger) error {
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	if err := tracing.WriteChromeTrace(f, spans); err != nil {
+		f.Close()
+		return err
+	}
+	if err := f.Close(); err != nil {
+		return err
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "\ntask: Profile written to %s (open it in https://ui.perfetto.dev)\n\n", path)
+	if err := tracing.Summarize(spans, 5).WriteSummary(&b); err != nil {
+		return err
+	}
+	log.Errf(logger.Default, "%s", b.String())
+	return nil
 }
 
 // runMCPServer serves the Taskfile over MCP on stdin/stdout. Nothing else may
 
@@ -26,7 +26,7 @@ function _task()
       _filedir -d
       return $?
     ;;
-    --cacert|--cert|--cert-key)
+    --cacert|--cert|--cert-key|--profile)
       _filedir
       return $?
     ;;
 
@@ -102,6 +102,7 @@ complete -c $GO_TASK_PROGNAME      -l explain                   -d 'explain whet
 complete -c $GO_TASK_PROGNAME      -l mcp                       -d 'serve tasks as tools over MCP (stdio)'
 complete -c $GO_TASK_PROGNAME      -l affected                  -d 'run or list only tasks affected by git changes'
 complete -c $GO_TASK_PROGNAME      -l since                     -d 'with --affected, compare with this git ref' -x
+complete -c $GO_TASK_PROGNAME      -l profile                   -d 'write a trace of the run to this file' -r
 complete -c $GO_TASK_PROGNAME -s t -l taskfile                  -d 'choose Taskfile to run'
 complete -c $GO_TASK_PROGNAME -s v -l verbose                   -d 'verbose output'
 complete -c $GO_TASK_PROGNAME      -l version                   -d 'show version'
 
@@ -61,6 +61,7 @@ Register-ArgumentCompleter -CommandName $cmdNames -ScriptBlock {
 			[CompletionResult]::new('--mcp', '--mcp', [CompletionResultType]::ParameterName, 'serve tasks as tools over MCP'),
 			[CompletionResult]::new('--affected', '--affected', [CompletionResultType]::ParameterName, 'only tasks affected by git changes'),
 			[CompletionResult]::new('--since', '--since', [CompletionResultType]::ParameterName, 'with --affected, compare with this git ref'),
+			[CompletionResult]::new('--profile', '--profile', [CompletionResultType]::ParameterName, 'write a trace of the run to this file'),
 			[CompletionResult]::new('-t', '-t', [CompletionResultType]::ParameterName, 'choose Taskfile'),
 			[CompletionResult]::new('--taskfile', '--taskfile', [CompletionResultType]::ParameterName, 'choose Taskfile'),
 			[CompletionResult]::new('-v', '-v', [CompletionResultType]::ParameterName, 'verbose output'),
 
@@ -105,6 +105,7 @@ _task() {
         '(--mcp)--mcp[serve tasks as tools over the Model Context Protocol]'
         '(--affected)--affected[run or list only tasks affected by git changes]'
         '(--since)--since[with --affected, compare with this git ref]:ref: '
+        '(--profile)--profile[write a trace of the run to this file]:file:_files'
         '(-t --taskfile)'{-t,--taskfile}'[specify a different taskfile]:taskfile:_files'
         '(-v --verbose)'{-v,--verbose}'[verbose mode]'
         '(-w --watch)'{-w,--watch}'[watch-mode for given tasks, re-run when inputs change]'
 
@@ -0,0 +1,117 @@
+# Profiling and OpenTelemetry tracing
+
+taskgraph can record what it does during a run: every task, the time spent
+waiting for dependencies, up-to-date checks, and every command. You can look at
+this as a profile on your machine, or send it to an OpenTelemetry backend from
+CI.
+
+## `--profile`: where did the time go?
+
+```shell
+taskgraph --profile trace.json ci
+```
+
+After the run, taskgraph writes the trace and prints a summary:
+
+```text
+task: Profile written to trace.json (open it in https://ui.perfetto.dev)
+
+Total: 1.09s
+
+Critical path:
+  ci  1.09s
+     └─ test  980ms
+        └─ build  670ms
+           └─ assets  261ms
+
+Slowest tasks (own time, excluding tasks they run):
+  build      408ms
+  test       310ms
+  assets     261ms
+  lint       211ms
+  gen        111ms
+```
+
+- **Critical path:** the chain of tasks that set the total time. At each
+  step it follows the task that finished last. Speeding up anything off this
+  path won't make the run faster.
+- **Slowest tasks:** ranked by their own time: their commands and checks,
+  minus the time covered by the tasks they run. Tasks that were up to date or
+  skipped are marked.
+
+`trace.json` uses the Chrome trace format. Open it in
+[ui.perfetto.dev](https://ui.perfetto.dev), `chrome://tracing` or
+[speedscope](https://www.speedscope.app) to see a timeline. Tasks that run in
+parallel appear on separate lanes:
+
+```text
+lane 1  ci ─────────────────────────────────────────────────────────
+        test ─────────────────────────────────────────────┐
+        build ────────────────────────────┐  go test ─────┘
+        gen ──┐   go build ───────────────┘
+lane 2  lint ────────┐
+lane 3  assets ──────────────┐
+```
+
+The profile is written even when a task fails.
+
+## OpenTelemetry
+
+When the standard OpenTelemetry environment variables point to an OTLP
+endpoint, taskgraph exports its spans there. You don't need a flag or any
+config file:
+
+```shell
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+taskgraph ci
+```
+
+The standard variables are supported:
+
+| Variable                                                                     | Effect                                             |
+| ---------------------------------------------------------------------------- | -------------------------------------------------- |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`          | Where to send spans. Tracing is on when either is set. |
+| `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`          | `http/protobuf` (default) or `grpc`.               |
+| `OTEL_EXPORTER_OTLP_HEADERS`                                                 | e.g. an API key for your backend.                  |
+| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`                              | Override `service.name` (default `taskgraph`) and add attributes. |
+| `OTEL_SDK_DISABLED=true`, `OTEL_TRACES_EXPORTER=none`                        | Turn it off.                                       |
+
+The spans are:
+
+| Span                                 | Attributes                                            |
+| ------------------------------------ | ----------------------------------------------------- |
+| `taskgraph <tasks>`                  | The root span for the whole invocation.               |
+| `task <name>`                        | `task.name`, `taskgraph.status` (`ran`, `up-to-date`, `skipped`, `failed`) |
+| `deps`                               | Time spent waiting for a task's dependencies.         |
+| `up-to-date check`                   | Preconditions plus the sources/status check, and `up_to_date`. |
+| `cmd <command>`                      | `task.name`, `cmd`                                    |
+| `waiting for ...`                    | Waiting for a `--concurrency` slot, or for a `run: once` task started elsewhere. |
+
+Failed tasks and commands record the error and set the span status to
+`Error`.
+
+### Joining a larger trace
+
+- **Incoming:** if the `TRACEPARENT` environment variable holds a W3C
+  trace context, taskgraph's root span becomes its child. So a CI system or
+  wrapper script that starts a trace sees taskgraph inside it.
+- **Outgoing:** every command a task runs gets `TRACEPARENT` set to its own
+  `cmd` span. Tools that read it (including a nested `taskgraph`, test
+  runners and build tools that support OpenTelemetry) add their spans under
+  the command that ran them.
+
+### Example: a local collector with Jaeger
+
+```shell
+docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+taskgraph ci
+# open http://localhost:16686 and search for the "taskgraph" service
+```
+
+## Notes
+
+- Tracing is off in watch mode (`--watch`), whose runs never end.
+- `--profile` cannot be combined with `--dry`, `--watch`, `--graph`,
+  `--explain`, `--mcp`, `--status` or `--summary`.
+- With neither `--profile` nor an OTLP endpoint, no spans are created at all.
@@ -13,6 +13,7 @@ import (
 	"github.com/XXXDelirious/taskgraph/internal/logger"
 	"github.com/XXXDelirious/taskgraph/internal/output"
 	"github.com/XXXDelirious/taskgraph/internal/sort"
+	"github.com/XXXDelirious/taskgraph/internal/tracing"
 	"github.com/XXXDelirious/taskgraph/taskfile/ast"
 )
 
@@ -81,6 +82,7 @@ type (
 		executionHashes      map[string]context.Context
 		executionHashesMutex sync.Mutex
 		watchedDirs          *xsync.Map[string, bool]
+		tracer               *tracing.Tracer
 	}
 	TempDir struct {
 		Remote      string
@@ -617,3 +619,17 @@ type failfastOption struct {
 func (o *failfastOption) ApplyToExecutor(e *Executor) {
 	e.Failfast = o.failfast
 }
+
+// WithTracer records the executor's work (tasks, deps, checks and commands)
+// with the given tracer. A nil tracer records nothing.
+func WithTracer(tracer *tracing.Tracer) ExecutorOption {
+	return &tracerOption{tracer}
+}
+
+type tracerOption struct {
+	tracer *tracing.Tracer
+}
+
+func (o *tracerOption) ApplyToExecutor(e *Executor) {
+	e.tracer = o.tracer
+}