Query telemetry go client

api-reference/go/workflows/ConfigureConsoleLogging.mdx

@@ -0,0 +1,48 @@
+---
+title: workflows.ConfigureConsoleLogging
+sidebarTitle: ConfigureConsoleLogging
+icon: rectangle-terminal
+---
+
+```go
+func ConfigureConsoleLogging(level slog.Level)
+```
+
+Configure the default `slog` logger to write workflow logs to standard output at the given level.
+
+The console handler composes with the Tilebox log exporter installed by `workflows.NewClient()`, so logs can be sent to Tilebox and printed locally. Calling `ConfigureConsoleLogging` more than once does not add duplicate console handlers.
+
+## Parameters
+
+<ParamField path="level" type="slog.Level" required>
+  The minimum log level to print to the console.
+</ParamField>
+
+## Returns
+
+Nothing.
+
+<RequestExample>
+```go Go
+import (
+    "context"
+    "log/slog"
+
+    "github.com/tilebox/tilebox-go/workflows/v1"
+)
+
+func main() {
+    ctx := context.Background()
+    workflows.ConfigureConsoleLogging(slog.LevelDebug)
+
+    client := workflows.NewClient()
+    runner, err := client.NewTaskRunner(ctx)
+    if err != nil {
+        slog.ErrorContext(ctx, "failed to create task runner", slog.Any("error", err))
+        return
+    }
+
+    runner.Run(ctx)
+}
+```
+</RequestExample>

api-reference/go/workflows/Jobs.QueryLogs.mdx

@@ -0,0 +1,71 @@
+---
+title: Client.Jobs.QueryLogs
+sidebarTitle: Jobs.QueryLogs
+icon: rectangle-terminal
+---
+
+```go
+func (*JobClient) QueryLogs(
+    ctx context.Context,
+    jobID uuid.UUID,
+    options ...workflows.TelemetryQueryOption,
+) iter.Seq2[*workflows.LogRecord, error]
+```
+
+Query log records emitted while running a job.
+
+The logs are lazily loaded and returned as a sequence of log records. Use [Collect](/api-reference/go/workflows/Collect) to transform the sequence into a slice.
+
+## Parameters
+
+<ParamField path="jobID" type="uuid.UUID" required>
+  The ID of the job to query logs for.
+</ParamField>
+<ParamField path="options" type="[]workflows.TelemetryQueryOption">
+  Options for querying logs.
+</ParamField>
+
+## Options
+
+<ParamField path="WithSortDirection(direction workflows.SortDirection)">
+  Sort logs by time. Use `workflows.Ascending` for oldest first or `workflows.Descending` for newest first.
+</ParamField>
+<ParamField path="WithLimit(limit int64)">
+  Limit the number of log records returned.
+</ParamField>
+
+## Returns
+
+A sequence of log records. Each record includes `Time`, `Level`, `Body`, and structured attributes.
+
+<RequestExample>
+```go Go
+import (
+    "fmt"
+    "log/slog"
+    "time"
+
+    "github.com/google/uuid"
+    "github.com/tilebox/tilebox-go/workflows/v1"
+)
+
+jobID := uuid.MustParse("019e07b1-916b-0630-f3ba-f1c33235d174")
+
+for record, err := range client.Jobs.QueryLogs(
+    ctx,
+    jobID,
+    workflows.WithSortDirection(workflows.Ascending),
+) {
+    if err != nil {
+        slog.ErrorContext(ctx, "failed to query job logs", slog.Any("error", err))
+        return
+    }
+
+    fmt.Printf("%s %-5s %s\n",
+        record.Time.Format(time.RFC3339),
+        record.Level,
+        record.Body,
+    )
+}
+```
+</RequestExample>

api-reference/go/workflows/Jobs.QuerySpans.mdx

@@ -0,0 +1,71 @@
+---
+title: Client.Jobs.QuerySpans
+sidebarTitle: Jobs.QuerySpans
+icon: chart-gantt
+---
+
+```go
+func (*JobClient) QuerySpans(
+    ctx context.Context,
+    jobID uuid.UUID,
+    options ...workflows.TelemetryQueryOption,
+) iter.Seq2[*workflows.Span, error]
+```
+
+Query spans emitted while running a job.
+
+The spans are lazily loaded and returned as a sequence of spans. Use [Collect](/api-reference/go/workflows/Collect) to transform the sequence into a slice.
+
+## Parameters
+
+<ParamField path="jobID" type="uuid.UUID" required>
+  The ID of the job to query spans for.
+</ParamField>
+<ParamField path="options" type="[]workflows.TelemetryQueryOption">
+  Options for querying spans.
+</ParamField>
+
+## Options
+
+<ParamField path="WithSortDirection(direction workflows.SortDirection)">
+  Sort spans by start time. Use `workflows.Ascending` for oldest first or `workflows.Descending` for newest first.
+</ParamField>
+<ParamField path="WithLimit(limit int64)">
+  Limit the number of spans returned.
+</ParamField>
+
+## Returns
+
+A sequence of spans. Each span includes `StartTime`, `Name`, `StatusCode`, `Attributes`, and `Duration()`.
+
+<RequestExample>
+```go Go
+import (
+    "fmt"
+    "log/slog"
+    "time"
+
+    "github.com/google/uuid"
+    "github.com/tilebox/tilebox-go/workflows/v1"
+)
+
+jobID := uuid.MustParse("019e07b1-916b-0630-f3ba-f1c33235d174")
+
+for span, err := range client.Jobs.QuerySpans(
+    ctx,
+    jobID,
+    workflows.WithSortDirection(workflows.Ascending),
+) {
+    if err != nil {
+        slog.ErrorContext(ctx, "failed to query job spans", slog.Any("error", err))
+        return
+    }
+
+    fmt.Printf("%s %-40s %s\n",
+        span.StartTime.Format(time.RFC3339),
+        span.Name,
+        span.Duration(),
+    )
+}
+```
+</RequestExample>

api-reference/go/workflows/WithSpan.mdx

@@ -0,0 +1,58 @@
+---
+title: workflows.WithSpan
+sidebarTitle: WithSpan
+icon: chart-gantt
+---
+
+```go
+func WithSpan(
+    ctx context.Context,
+    name string,
+    f func(ctx context.Context) error,
+) error
+```
+
+Wrap a function with a [tracing span](/workflows/observability/tracing) using the current task runner's tracer.
+
+Use `WithSpan` inside a task `Execute` method. If the context is not a task execution context, the function runs without creating a span.
+
+## Parameters
+
+<ParamField path="ctx" type="context.Context" required>
+  The task execution context.
+</ParamField>
+<ParamField path="name" type="string" required>
+  The name of the span.
+</ParamField>
+<ParamField path="f" type="func(context.Context) error" required>
+  The function to wrap.
+</ParamField>
+
+## Returns
+
+The error returned by `f`, if any.
+
+<RequestExample>
+```go Go
+import (
+    "context"
+    "fmt"
+
+    "github.com/tilebox/tilebox-go/workflows/v1"
+)
+
+type ProcessScene struct{}
+
+func (t *ProcessScene) Execute(ctx context.Context) error {
+    err := workflows.WithSpan(ctx, "write-output", func(ctx context.Context) error {
+        // Write output here.
+        return nil
+    })
+    if err != nil {
+        return fmt.Errorf("failed to write output: %w", err)
+    }
+
+    return nil
+}
+```
+</RequestExample>

api-reference/go/workflows/WithSpanResult.mdx

@@ -0,0 +1,60 @@
+---
+title: workflows.WithSpanResult
+sidebarTitle: WithSpanResult
+icon: chart-gantt
+---
+
+```go
+func WithSpanResult[Result any](
+    ctx context.Context,
+    name string,
+    f func(ctx context.Context) (Result, error),
+) (Result, error)
+```
+
+Wrap a function with a [tracing span](/workflows/observability/tracing) using the current task runner's tracer and return the function result.
+
+Use `WithSpanResult` inside a task `Execute` method. If the context is not a task execution context, the function runs without creating a span.
+
+## Parameters
+
+<ParamField path="ctx" type="context.Context" required>
+  The task execution context.
+</ParamField>
+<ParamField path="name" type="string" required>
+  The name of the span.
+</ParamField>
+<ParamField path="f" type="func(context.Context) (Result, error)" required>
+  The function to wrap.
+</ParamField>
+
+## Returns
+
+The result and error returned by `f`.
+
+<RequestExample>
+```go Go
+import (
+    "context"
+    "fmt"
+    "log/slog"
+
+    "github.com/tilebox/tilebox-go/workflows/v1"
+)
+
+type ProcessScene struct{}
+
+func (t *ProcessScene) Execute(ctx context.Context) error {
+    pixels, err := workflows.WithSpanResult(ctx, "compute-index", func(ctx context.Context) (int, error) {
+        // Compute an index here.
+        return 42, nil
+    })
+    if err != nil {
+        return fmt.Errorf("failed to compute index: %w", err)
+    }
+
+    slog.InfoContext(ctx, "index computed", slog.Int("pixels", pixels))
+    return nil
+}
+```
+</RequestExample>

docs.json

@@ -254,6 +254,9 @@
                   "api-reference/go/workflows/GetCurrentCluster",
                   "api-reference/go/workflows/SubmitSubtask",
                   "api-reference/go/workflows/SubmitSubtasks",
+                  "api-reference/go/workflows/ConfigureConsoleLogging",
+                  "api-reference/go/workflows/WithSpan",
+                  "api-reference/go/workflows/WithSpanResult",
                   "api-reference/go/workflows/WithTaskSpan",
                   "api-reference/go/workflows/WithTaskSpanResult",
                   "api-reference/go/workflows/NewTaskRunner",
@@ -268,6 +271,8 @@
                   "api-reference/go/workflows/Jobs.Get",
                   "api-reference/go/workflows/Jobs.Retry",
                   "api-reference/go/workflows/Jobs.Cancel",
+                  "api-reference/go/workflows/Jobs.QueryLogs",
+                  "api-reference/go/workflows/Jobs.QuerySpans",
                   "api-reference/go/workflows/Jobs.Query",
                   "api-reference/go/workflows/Collect"
                 ]