Frodo Library - v5.0.0-47
    Preparing search index...

    Type Alias Log

    type Log = {
        createLogApiKey(keyName: string): Promise<LogApiKey>;
        createLogTailStream(source: string): LogTailStream;
        deleteLogApiKey(keyId: string): Promise<LogApiKey>;
        deleteLogApiKeys(): Promise<LogApiKey[]>;
        fetch(
            source: string,
            startTs: string,
            endTs: string,
            cookie: string,
            txid: string,
            filter: string,
        ): Promise<LogEventsPage>;
        getDefaultNoiseFilter(): string[];
        getLogApiKey(keyId: string): Promise<LogApiKey>;
        getLogApiKeys(): Promise<LogApiKey[]>;
        getLogSources(): Promise<string[]>;
        isLogApiKeyValid(keyId: string, secret: string): Promise<boolean>;
        resolveLevel(level: string | number): string[];
        resolvePayloadLevel(log: LogEventSkeleton): string;
        searchEvents(
            source: string,
            startTs: string,
            endTs: string,
            eventNames?: string[],
            principal?: string,
            maxEvents?: number,
            dedupeByTransactionId?: boolean,
            rateLimitShare?: number,
        ): Promise<LogEventSkeleton[]>;
        tail(source: string, cookie: string): Promise<LogEventsPage>;
    }
    Index
    • Create log api key

      Parameters

      • keyName: string

        human-readable key name

      Returns Promise<LogApiKey>

      a promise resolving to an object containing the log api key and secret

    • Creates a stateful, deduped consumer of tail() -- everything a caller doing a live polling loop (e.g. an interactive follow-style view) needs without reimplementing cookie-tracking or dedup itself.

      Parameters

      • source: string

        log source(s) to tail

      Returns LogTailStream

      a stream object with a poll() method and the rateLimit of the latest answer

      PingOne AIC's own tail-endpoint documentation is explicit that each subsequent call's range "starts from the last returned log entry in the previous result (inclusive)" -- the boundary event is documented to repeat by design, and the endpoint returns no unique event id at all to tell repeats apart with (confirmed live: unlike fetch(), whose results do carry _id). A real live poll loop against am-authentication also showed tail() redeliver a whole earlier batch verbatim -- sometimes even within one poll's own result array, not just across a cookie boundary -- so this dedupes broadly by event content, not merely by skipping one known boundary event.

      rateLimit of the stream is the state of the Log API limit as the latest answer reported it, and a poll that the API rejects for the rate limit fails like tail() (code LOG_API_RATE_LIMITED) without losing the position of the stream; the caller decides when to poll again.

    • Delete log api key

      Parameters

      • keyId: string

        key id

      Returns Promise<LogApiKey>

      a promise resolving to an object containing the log api key

    • Fetch logs

      Parameters

      • source: string

        log source(s) to tail

      • startTs: string

        start timestamp

      • endTs: string

        end timestamp

      • cookie: string

        paged results cookie

      • txid: string

        transaction id

      • filter: string

        query filter

      Returns Promise<LogEventsPage>

      promise resolving to paged log event result; rateLimit holds the rate limit state that the answer reported (limit, remaining requests, reset time), if it carried the headers

      The Log API throttles the requests of an environment, and the limit is shared by everything that reads its logs. A request that the API rejects for that reason is sent once more after the end of the window, when the answer says when that is (Retry-After or X-RateLimit-Reset). Otherwise, and when the second request is rejected too, the call ends with a FrodoError that has the code LOG_API_RATE_LIMITED and, if the answer carried the X-RateLimit-* headers, rateLimit.

    • Get default noise filter

      Returns string[]

      array of default event types and loggers to be filtered out

    • Get available log sources

      Returns Promise<string[]>

      promise resolving to an array of available log sources

    • Validate log api key and secret

      Parameters

      • keyId: string

        log api key id

      • secret: string

        log api secret

      Returns Promise<boolean>

      a promise resolving to true if the key is valid, false otherwise

    • Resolve log level to an array of effective log levels

      Parameters

      • level: string | number

        string or numeric log level: 'FATAL', 'ERROR', 'WARN', 'INFO', 'DEBUG', 'TRACE', 'ALL', 0, 1, 2, 3, 4

      Returns string[]

      array of effective log levels

    • Search audit events by event name(s) and/or principal, across the full time range (auto-paginating), with client-side dedup by transaction id.

      Parameters

      • source: string

        log source(s) to search, e.g. am-authentication

      • startTs: string

        start timestamp

      • endTs: string

        end timestamp

      • OptionaleventNames: string[]

        optional event names to match (OR'd together server-side)

      • Optionalprincipal: string

        optional principal substring to match against payload.userId (co)

      • OptionalmaxEvents: number

        safety cap on total events fetched across pages

      • OptionaldedupeByTransactionId: boolean

        collapse multiple events sharing a transaction id (e.g. a failed-then-successful retry) down to the last one seen; default true

      • OptionalrateLimitShare: number

        the share of the requests per window that the Log API allows (as the API reports it) that the search may use, greater than 0 and at most 1; default 0.5. The rest is left to other readers of the logs of the environment, such as a running tail.

      Returns Promise<LogEventSkeleton[]>

      promise resolving to the matched (and optionally deduped) events

    • Tail logs

      Parameters

      • source: string

        log source(s) to tail

      • cookie: string

        paged results cookie

      Returns Promise<LogEventsPage>

      promise resolving to paged log event result; rateLimit holds the rate limit state that the answer reported (limit, remaining requests, reset time), if it carried the headers

      The Log API throttles the requests of an environment, and the limit is shared by everything that reads its logs. A request that the API rejects for that reason is not waited for here: it ends with a FrodoError that has the code LOG_API_RATE_LIMITED and, if the answer carried the X-RateLimit-* headers, rateLimit, whose resetAt is when the window resets. The caller that polls owns the waiting.