Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 21 additions & 10 deletions docs/n8n_otel_set.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,25 @@ Fully replace OpenTelemetry settings
### Synopsis

Fully replace the instance OpenTelemetry configuration from strict JSON. This
is a PUT, not a patch: every field is required except exporterProtocol. Omitting
that field selects http/protobuf. Start from 'n8n otel get --output json'.
is a PUT, not a patch: every field is required except exporterProtocol,
emitWorkflowStartSpan, and emitNodeStartSpan. Omitting exporterProtocol selects
http/protobuf. The two start-span fields are omitted = false on the server: a
document without them turns both spans off, so pass the current values or use
--input from 'n8n otel get --output json', which round-trips them losslessly.
--emit-workflow-start-span and --emit-node-start-span set or override them in
the --input document. Instances older than these settings do not report them;
leave them out there.

A successful update is applied to the running instance immediately and can
change or stop exported traces, so interactive runs ask for confirmation and
non-interactive runs require --yes. --input - also requires --yes because stdin
cannot hold both JSON and a confirmation answer.

Environment-managed fields are read-only. Re-submit their effective GET values
unchanged, or change the environment configuration. Exporter headers may be
credentials; response details are redacted on errors. Requires otel:manage.
unchanged, or change the environment configuration. Omitting a start-span field
that the environment pins to true is a change and answers 409. Exporter headers
may be credentials; response details are redacted on errors. Requires
otel:manage.

```
n8n otel set [flags]
Expand All @@ -27,18 +35,21 @@ n8n otel set [flags]
umask 077 && n8n otel get --output json > otel.json
n8n otel set --input otel.json
n8n otel set --input otel.json --yes --output json
n8n otel set --input otel.json --emit-workflow-start-span --emit-node-start-span=false
n8n otel set --input - --yes < otel.json
```

### Options

```
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
-h, --help help for set
--input string full OpenTelemetry settings JSON file path, or - for stdin (required; maximum 1 MiB)
--output string output format: text or json (JSON includes possibly sensitive exporter headers) (default "text")
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--yes confirm full replacement and immediate runtime application without prompting (required when stdin is not interactive)
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
--emit-node-start-span emit a 0 ms node.execute.started span when each node span starts, doubling node spans; true or false, overrides emitNodeStartSpan in --input (default: the --input value, and false on the server when both omit it)
--emit-workflow-start-span emit a 0 ms workflow.execute.started span when each execution starts; true or false, overrides emitWorkflowStartSpan in --input (default: the --input value, and false on the server when both omit it)
-h, --help help for set
--input string full OpenTelemetry settings JSON file path, or - for stdin (required; maximum 1 MiB)
--output string output format: text or json (JSON includes possibly sensitive exporter headers) (default "text")
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--yes confirm full replacement and immediate runtime application without prompting (required when stdin is not interactive)
```

### SEE ALSO
Expand Down
35 changes: 23 additions & 12 deletions docs/n8n_saml_set.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,20 @@ Fully replace SAML SSO configuration
### Synopsis

Fully replace the instance SAML SSO configuration from strict JSON. This is
a PUT, not a patch: all 15 writable top-level fields and every nested mapping
and signature field are required, including false, empty-string, and empty-array
values. Start from 'n8n saml get --output json'. Read-only entityID and returnUrl
are accepted for that round trip but ignored on set. Leave returned redaction
placeholders unchanged to preserve metadata, private key, and certificate; use
empty strings to clear supported values or plaintext to replace them.
a PUT, not a patch: every writable top-level field (16 on current n8n) and every
nested mapping and signature field is required, including false, empty-string,
and empty-array values. Start from 'n8n saml get --output json': that document
round-trips losslessly, including emailVerifiedRequired and mapping.emailVerified.
Read-only entityID and returnUrl are accepted for that round trip but ignored on
set. Leave returned redaction placeholders unchanged to preserve metadata,
private key, and certificate; use empty strings to clear supported values or
plaintext to replace them.

Current n8n requires emailVerifiedRequired and mapping.emailVerified and answers
400 without them; older instances do not know them, so a document without them
is sent as is with a warning. --email-verified-required and
--email-verified-attribute set or override those two fields in the --input
document, e.g. when it came from an older instance.

Every replacement asks for confirmation because changing SAML settings can alter
the login flow immediately. Non-interactive use and --input - require --yes.
Expand All @@ -28,18 +36,21 @@ n8n saml set [flags]
umask 077 && n8n saml get --output json > saml.json
n8n saml set --input saml.json
n8n saml set --input saml.json --yes --output json
n8n saml set --input saml.json --email-verified-required --email-verified-attribute email_verified
n8n saml set --input - --yes < saml.json
```

### Options

```
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
-h, --help help for set
--input string full SAML configuration JSON file path, or - for stdin (required; maximum 1 MiB; may contain private material)
--output string output format: text or json (secret-bearing values are returned only as n8n placeholders) (default "text")
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--yes confirm full replacement and possible login-flow changes without prompting (required for non-interactive use)
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
--email-verified-attribute string SAML attribute whose true/false value states the email is verified, empty string when unused; overrides mapping.emailVerified in --input (default: the --input value)
--email-verified-required require the identity provider to assert a verified email before a login links to an existing user by email; true or false, overrides emailVerifiedRequired in --input (default: the --input value)
-h, --help help for set
--input string full SAML configuration JSON file path, or - for stdin (required; maximum 1 MiB; may contain private material)
--output string output format: text or json (secret-bearing values are returned only as n8n placeholders) (default "text")
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--yes confirm full replacement and possible login-flow changes without prompting (required for non-interactive use)
```

### SEE ALSO
Expand Down
62 changes: 50 additions & 12 deletions internal/cli/otel.go
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,12 @@ func runOtelGet(ctx context.Context, opts Options, f otelGetFlags) error {
}

type otelSetFlags struct {
instance instanceFlags
input string
yes bool
output string
instance instanceFlags
input string
emitWorkflowStartSpan bool
emitNodeStartSpan bool
yes bool
output string
}

func newOtelSetCommand(opts Options) *cobra.Command {
Expand All @@ -105,32 +107,53 @@ func newOtelSetCommand(opts Options) *cobra.Command {
Use: "set",
Short: "Fully replace OpenTelemetry settings",
Long: "Fully replace the instance OpenTelemetry configuration from strict JSON. This\n" +
"is a PUT, not a patch: every field is required except exporterProtocol. Omitting\n" +
"that field selects http/protobuf. Start from 'n8n otel get --output json'.\n\n" +
"is a PUT, not a patch: every field is required except exporterProtocol,\n" +
"emitWorkflowStartSpan, and emitNodeStartSpan. Omitting exporterProtocol selects\n" +
"http/protobuf. The two start-span fields are omitted = false on the server: a\n" +
"document without them turns both spans off, so pass the current values or use\n" +
"--input from 'n8n otel get --output json', which round-trips them losslessly.\n" +
"--emit-workflow-start-span and --emit-node-start-span set or override them in\n" +
"the --input document. Instances older than these settings do not report them;\n" +
"leave them out there.\n\n" +
"A successful update is applied to the running instance immediately and can\n" +
"change or stop exported traces, so interactive runs ask for confirmation and\n" +
"non-interactive runs require --yes. --input - also requires --yes because stdin\n" +
"cannot hold both JSON and a confirmation answer.\n\n" +
"Environment-managed fields are read-only. Re-submit their effective GET values\n" +
"unchanged, or change the environment configuration. Exporter headers may be\n" +
"credentials; response details are redacted on errors. Requires otel:manage.",
"unchanged, or change the environment configuration. Omitting a start-span field\n" +
"that the environment pins to true is a change and answers 409. Exporter headers\n" +
"may be credentials; response details are redacted on errors. Requires\n" +
"otel:manage.",
Example: " umask 077 && n8n otel get --output json > otel.json\n" +
" n8n otel set --input otel.json\n" +
" n8n otel set --input otel.json --yes --output json\n" +
" n8n otel set --input otel.json --emit-workflow-start-span --emit-node-start-span=false\n" +
" n8n otel set --input - --yes < otel.json",
Args: cobra.NoArgs,
RunE: func(cmd *cobra.Command, _ []string) error {
return runOtelSet(cmd.Context(), opts, f)
return runOtelSet(cmd.Context(), opts, f, otelSetOverrides{
emitWorkflowStartSpan: cmd.Flags().Changed("emit-workflow-start-span"),
emitNodeStartSpan: cmd.Flags().Changed("emit-node-start-span"),
})
},
}
f.instance.register(cmd)
cmd.Flags().StringVar(&f.input, "input", "", "full OpenTelemetry settings JSON file path, or - for stdin (required; maximum 1 MiB)")
cmd.Flags().BoolVar(&f.emitWorkflowStartSpan, "emit-workflow-start-span", false, "emit a 0 ms workflow.execute.started span when each execution starts; true or false, overrides emitWorkflowStartSpan in --input (default: the --input value, and false on the server when both omit it)")
cmd.Flags().BoolVar(&f.emitNodeStartSpan, "emit-node-start-span", false, "emit a 0 ms node.execute.started span when each node span starts, doubling node spans; true or false, overrides emitNodeStartSpan in --input (default: the --input value, and false on the server when both omit it)")
cmd.Flags().BoolVar(&f.yes, "yes", false, "confirm full replacement and immediate runtime application without prompting (required when stdin is not interactive)")
cmd.Flags().StringVar(&f.output, "output", outputText, "output format: text or json (JSON includes possibly sensitive exporter headers)")
return cmd
}

func runOtelSet(ctx context.Context, opts Options, f otelSetFlags) error {
// otelSetOverrides records which field flags were passed, so an explicit false
// still overrides the --input document.
type otelSetOverrides struct {
emitWorkflowStartSpan bool
emitNodeStartSpan bool
}

func runOtelSet(ctx context.Context, opts Options, f otelSetFlags, overrides otelSetOverrides) error {
if err := validateOutput(f.output); err != nil {
return err
}
Expand All @@ -141,9 +164,18 @@ func runOtelSet(ctx context.Context, opts Options, f otelSetFlags) error {
if err := readOtelDocument(opts, f.input, &request, "settings"); err != nil {
return err
}
if overrides.emitWorkflowStartSpan {
request.EmitWorkflowStartSpan = &f.emitWorkflowStartSpan
}
if overrides.emitNodeStartSpan {
request.EmitNodeStartSpan = &f.emitNodeStartSpan
}
if err := request.Validate(); err != nil {
return err
}
if missing := request.MissingStartSpans(); len(missing) > 0 {
fmt.Fprintf(opts.Streams.Err, "Warning: --input omits %s. Instances that support them set them to false (409 if pinned to true by environment); older instances do not know them. Add them from 'n8n otel get --output json' or pass --emit-workflow-start-span and --emit-node-start-span.\n", strings.Join(missing, " and "))
}
client, resolution, err := opts.apiClient(f.instance)
if err != nil {
return err
Expand Down Expand Up @@ -276,6 +308,12 @@ func writeOtelSettings(opts Options, resolution config.Resolution, heading strin
fmt.Fprintf(tw, "Trace sample rate:\t%g\n", settings.TracesSampleRate)
fmt.Fprintf(tw, "Startup connectivity timeout:\t%d ms\n", settings.StartupConnectivityTimeoutMs)
fmt.Fprintf(tw, "Include node spans:\t%s\n", yesNo(settings.IncludeNodeSpans))
if settings.EmitWorkflowStartSpan != nil {
fmt.Fprintf(tw, "Emit workflow start span:\t%s\n", yesNo(*settings.EmitWorkflowStartSpan))
}
if settings.EmitNodeStartSpan != nil {
fmt.Fprintf(tw, "Emit node start span:\t%s\n", yesNo(*settings.EmitNodeStartSpan))
}
fmt.Fprintf(tw, "Inject outbound trace context:\t%s\n", yesNo(settings.InjectOutbound))
fmt.Fprintf(tw, "Production executions only:\t%s\n", yesNo(settings.ProductionExecutionsOnly))
if applied {
Expand All @@ -294,13 +332,13 @@ func otelHeadersStatus(headers string) string {
func otelAPIError(err error, resolution config.Resolution, action string) error {
switch {
case n8n.IsStatus(err, http.StatusBadRequest) && action == "update":
return fmt.Errorf("%s rejected the full OpenTelemetry replacement (400): include every field except optional exporterProtocol, which defaults to http/protobuf; collector response details were redacted", resolution.URL)
return fmt.Errorf("%s rejected the full OpenTelemetry replacement (400): include every field except optional exporterProtocol, which defaults to http/protobuf, and the start-span fields, which default to false and which older instances may not accept; collector response details were redacted", resolution.URL)
case n8n.IsStatus(err, http.StatusBadRequest) && action == "test":
return fmt.Errorf("%s rejected the OpenTelemetry test connection details (400): check the endpoint, protocol, service name, headers, and timeout; collector response details were redacted", resolution.URL)
case n8n.IsForbidden(err):
return forbiddenScopeError(err, resolution, "OpenTelemetry settings "+action, allOf("otel:manage"), "", otelResource)
case n8n.IsConflict(err) && action == "update":
return fmt.Errorf("%s refused the OpenTelemetry replacement (409): one or more changed fields are managed by environment variables, so no changes were made; run 'n8n otel get', re-submit environment-managed values unchanged, or change the environment configuration and restart n8n", resolution.URL)
return fmt.Errorf("%s refused the OpenTelemetry replacement (409): one or more changed fields are managed by environment variables, so no changes were made; omitting emitWorkflowStartSpan or emitNodeStartSpan counts as a change when the environment pins it to true; run 'n8n otel get', re-submit environment-managed values unchanged (or pass --emit-workflow-start-span / --emit-node-start-span), or change the environment configuration and restart n8n", resolution.URL)
default:
return apiError(err, resolution, otelResource)
}
Expand Down
Loading
Loading