ConvertTo‑ShpOtelTrace

SYNOPSIS

Translates a ShellPilot Event stream into OpenTelemetry-compatible spans, without taking an OpenTelemetry dependency.

SYNTAX

Path (Default)

ConvertTo-ShpOtelTrace [-Path] <String> [-MappingVersion <String>] [-IncludeContent] [-ServiceName <String>]
 [-Format <String>] [<CommonParameters>]

InputObject

ConvertTo-ShpOtelTrace -InputObject <Object[]> [-MappingVersion <String>] [-IncludeContent]
 [-ServiceName <String>] [-Format <String>] [<CommonParameters>]

DESCRIPTION

Reads the headless JSONL Event stream (Invoke-Shp -EventStream) and returns the same run expressed as spans: one per Turn, model request, Tool call, policy decision, MCP request and Subagent, carrying usage, cost, finish and error facts as attributes.

It is a TRANSLATION, not an exporter. Nothing here opens a socket, starts a background process or links an SDK: the module stays pure PowerShell with no runtime dependency, and shipping the result to a collector is the caller's step - -Format Otlp produces the resourceSpans document an OTLP/HTTP endpoint accepts, and the caller posts it with whatever they already trust.

Span identity is not invented here. Every record carries the trace, span and parent identity stamped when it was written, so the tree is rebuilt from the file alone and a Batch, Job or Subagent record lands under the parent that dispatched it. A record with no trace identity - a stream written before spec 042 - is dropped and counted rather than given a synthetic trace, because a fabricated tree is harder to notice than a missing one.

CONTENT IS OFF BY DEFAULT. Prompts, answers, Tool arguments, Tool result previews, reasoning traces and error messages are withheld; only their measurable shape (lengths, counts, decisions, identities) is exported. -IncludeContent opts in, and what it includes is passed through the module's existing redaction seam first, so a custom Set-ShpRedactionPolicy rule covers an export too.

The MAPPING VERSION IS DEVELOPMENTAL and says so on every report. The semantic conventions for generative-AI and agent telemetry are still moving, so attribute names here may change; state -MappingVersion to assert the one you built against and get an error rather than a silent re-shape.

Span names are deliberately low cardinality - no path, URL or identifier is ever part of a name - so a backend can aggregate them.

EXAMPLES

EXAMPLE 1

ConvertTo-ShpOtelTrace -Path ./run.jsonl

Returns the run as spans, with no prompt, answer or Tool content.

EXAMPLE 2

ConvertTo-ShpOtelTrace -Path ./run.jsonl -Format Otlp -ServiceName 'ci-agent' |
    ConvertTo-Json -Depth 12 | Set-Content ./otlp.json

Produces the document an OTLP/HTTP collector accepts.

PARAMETERS

-Format

'Span' (default) returns ShellPilot.OtelSpan objects on a report object; 'Otlp' returns the OTLP/JSON resourceSpans document.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: Span
Accept pipeline input: False
Accept wildcard characters: False

-IncludeContent

Include prompt, answer, argument, result-preview, reasoning and error message text, after redaction. Off by default.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-InputObject

Already-parsed event records, by pipeline or by value, instead of a file.

Type: Object[]
Parameter Sets: InputObject
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-MappingVersion

The mapping version this caller was written against. Refused when it is not one this module implements.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Path

The Event stream file to translate. One JSON object per line.

Type: String
Parameter Sets: Path
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ServiceName

The service.name resource attribute of an -Format Otlp document.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

ShellPilot.OtelTrace (MappingVersion, MappingStability, Spans,

Warnings, DroppedRecordCount, ContentIncluded), or the OTLP document.

NOTES

RELATED LINKS

Invoke-Shp

Set-ShpRedactionPolicy