nsmcp::LogService method start (public)

 <instance of nsmcp::LogService> start context operation \
    [ identifier ]

Defined in /usr/local/ns/tcl/nsmcp/log-tools.tcl

Queue an owned diagnostic log operation. Validate the operation and establish its immutable options, limits and job metadata before scheduling work.

Parameters:

context (required)

Authenticated request context carrying the principal, grants and selected server.

operation (required)

Configured diagnostic operation to run.

identifier (optional)

Complete log-thread identifier, or the raw identifier field when parsing access records.

Returns:

A rooted JSON job descriptor.

Testcases:

No testcase defined.

Source code:

:require $context
if {$operation ni {errors requestContext requestContexts accessSummary accessFileSummary errorSummary routingSummary}} {
    error "invalid log operation"
}
if {$operation eq "requestContext" && ![::nsmcp::logRecordParser validRequestIdentifier $identifier]} {
    return -code error -errorcode {NSMCP RPC -32602} "Invalid request identifier"
}
if {$operation eq "requestContexts"} {
    set ids [dict get $identifier identifiers]
    if {[llength $ids] < 1 || [llength $ids] > 20} {
        return -code error -errorcode {NSMCP RPC -32602} "Expected 1..20 identifiers"
    }
    foreach id $ids {
        if {![::nsmcp::logRecordParser validRequestIdentifier $id]} {
            return -code error -errorcode {NSMCP RPC -32602} "Expected dash-delimited identifiers"
        }
    }
}
if {$operation eq "accessFileSummary"} {
    dict set identifier scanLimits [dict merge [::nsmcp::accessAggregateSettings] [dict create bytes [:accessBudget]]]
}
set lifetime ${:lifetime}
if {$operation eq "accessFileSummary" && (![dict exists $identifier mode] || [dict get $identifier mode] eq "summary")} {
    set lifetime [ns_baseunit -time [ns_config ns/server/[ns_info server]/module/nsmcp accessScanLifetime 2h]]
    if {$lifetime<1 || $lifetime>86400} {
        error "accessScanLifetime must be between 1s and 24h"
    }
}
set requiresRuntime [expr {$operation eq "routingSummary"}]
if {$requiresRuntime} {
    ${:authorizer} require $context diagnostics.runtime.read
}
set requiresPeers [expr {($operation eq "accessSummary" &&
    ([dict exists $identifier peer] || ([dict exists $identifier includePeerAddresses] && [dict get $identifier includePeerAddresses])))
    || ($operation eq "routingSummary" && [dict get $identifier options includePeerAddresses])}]
if {$requiresPeers} {
    ${:authorizer} require $context diagnostics.logs.peers.read
}
ns_mutex lock ${:mutex}
try {
    foreach key [nsv_array names ${:store}] {
        set record [nsv_get ${:store} $key]
        if {[dict get $record expires] <= [clock seconds] && [dict get $record status] in {complete failed}} {
            if {[dict exists $record identifier scanState] && [dict exists $record operation] && [dict get $record operation] eq "accessFileSummary"} {
                ::nsmcp::accessScanCleanup [dict get $record identifier scanState]
            }
            nsv_unset ${:store} $key
        }
    }
    if {[llength [nsv_array names ${:store}]] >= ${:maxJobs}} {
        error "log job limit reached"
    }
    set handle [ns_crypto::randombytes -encoding hex 32]
    set record [dict create principal [$context principal] server [$context server]  expires [expr {[clock seconds]+$lifetime}] queuedMs [clock milliseconds] workerMs 0 status queued operation $operation identifier $identifier mappings {} requiresPeers $requiresPeers requiresRuntime $requiresRuntime]
    if {$operation eq "accessFileSummary"} {
        dict set record progress [::nsmcp::accessScanProgress {} queued [dict create files {} index 0 examinedBytes 0 limits [dict get $identifier scanLimits]] {}]
    }
    set windowHandle {}
    if {$operation eq "accessSummary"} {
        set windowHandle [ns_crypto::randombytes -encoding hex 32]
        dict set record windowHandle $windowHandle
        dict set record window [dict create from [dict get $identifier from] to [dict get $identifier to]]
    }
    nsv_set ${:store} $handle $record
    try {
        ns_job queue -detached ${:queue} [list [self] run $handle]
    } on error {message options} {
        nsv_unset ${:store} $handle
        return -options $options $message
    }
} finally {
    ns_mutex unlock ${:mutex}
}
set data [list jobHandle string $handle status string queued server string [ns_info server]]
if {$windowHandle ne ""} {
    lappend data windowHandle string $windowHandle
}
if {$operation eq "accessFileSummary"} {
    lappend data progress object [dict get $record progress]
}
return [list {} object $data]

XQL Not present:

Generic, PostgreSQL, Oracle