Skip to content

Conversation

kyle-a-wong
Copy link
Contributor

This new builtin creates a transaction diagnostic request
to capture and generate a transaction bundle for a specified
transaction fingerprint id.

This builting has the following signature:
crdb_internal.request_transaction_bundle(transaction_fingerprint_id: string, sampling_probability: float, min_execution_latency: interval, expires_after: interval, redacted: bool) -> bool

transaction_fingerprint_id - a hex-encoded fingerprint id for the transaction
intended to be captured
sampling_probability - the probability used to determine if a transaction bundle
should be recorded. This value must be between [0,1].
min_execution_latency - the minimum execution latency for a transaction. If the
execution time of a transaction is lower than this value,
the request will not be considered fulfilled and will remain
uncompleted. If sampling_probability is non-zero, this value
must also be non-zero.
expires_after - the duration in which a request will remain open. If zero is provided,
the request will exist until it is completed or deleted.
redacted - whether or not the collected bundle will be redacted or unredacted

The builtin will return true if the request is generated successfully, or false
if creating a request for transaction fingerprint id that doesn't exist. Existence
of a transaction fingerprint id is determined by its existence in
crdb_internal.transaction_statistics. This is necessary because it is currently
the only system of record for transaction fingerprints in cockroachdb.

The user making the request for a transaction diagnostics bundle must have either
VIEWACTIVITY or VIEWACTIVITYREDACTED grants to call this builtin. If they have
VIEWACTIVITYREDACTED, only redacted bundles can be requested.

Resolves: CRDB-54322
Epic: CRDB-53541
Release note (sql change): adds a new builtin:
crdb_internal.request_transaction_bundle(transaction_fingerprint_id: string, sampling_probability: float, min_execution_latency: interval, expires_after: interval, redacted: bool) -> bool

transaction_fingerprint_id - a hex-encoded fingerprint id for the transaction
intended to be captured
sampling_probability - the probability used to determine if a transaction bundle
should be recorded. This value must be between [0,1].
min_execution_latency - the minimum execution latency for a transaction. If the
execution time of a transaction is lower than this value,
the request will not be considered fulfilled and will remain
uncompleted. If sampling_probability is non-zero, this value
must also be non-zero.
expires_after - the duration in which a request will remain open. If zero is provided,
the request will exist until it is completed or deleted.
redacted - whether or not the collected bundle will be redacted or unredacted

The built-in will return true if the request is generated successfully, or false
if creating a request for transaction fingerprint id that doesn't exist.

The user making the request for a transaction diagnostics bundle must have either
VIEWACTIVITY or VIEWACTIVITYREDACTED grants to call this builtin. If they have
VIEWACTIVITYREDACTED, only redacted bundles can be requested.


note: This is a stacked PR, only the last commit should be reviewed

@kyle-a-wong kyle-a-wong requested review from dhartunian and a team September 16, 2025 18:38
@kyle-a-wong kyle-a-wong requested a review from a team as a code owner September 16, 2025 18:38
Copy link

blathers-crl bot commented Sep 16, 2025

Your pull request contains more than 1000 changes. It is strongly encouraged to split big PRs into smaller chunks.

🦉 Hoot! I am a Blathers, a bot for CockroachDB. My owner is dev-inf.

@cockroach-teamcity
Copy link
Member

This change is Reviewable

@kyle-a-wong kyle-a-wong force-pushed the txn_bundle_builtin branch 8 times, most recently from bc6d614 to 249a10c Compare September 18, 2025 05:05
@rafiss rafiss removed the request for review from a team September 22, 2025 20:10
@kyle-a-wong kyle-a-wong force-pushed the txn_bundle_builtin branch 5 times, most recently from e876738 to eca2303 Compare September 23, 2025 19:36
Copy link
Collaborator

@dhartunian dhartunian left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: spelling in commit message: This builting has the following signature:

This new builtin creates a transaction diagnostic request
to capture and generate a transaction bundle for a specified
transaction fingerprint id.

This builtin has the following signature:
```
crdb_internal.request_transaction_bundle(
transaction_fingerprint_id: string,
sampling_probability: float,
min_execution_latency: interval,
expires_after: interval,
redacted: bool) -> (int as request_id, bool as created)
```

transaction_fingerprint_id - a hex-encoded fingerprint id for the transaction
                             intended to be captured
sampling_probability - the probability used to determine if a transaction bundle
                       should be recorded. This value must be between [0,1].
min_execution_latency - the minimum execution latency for a transaction. If the
                        execution time of a transaction is lower than this value,
                        the request will not be considered fulfilled and will remain
                        uncompleted. If sampling_probability is non-zero, this value
                        must also be non-zero.
expires_after - the duration in which a request will remain open. If zero is provided,
                the request will exist until it is completed or deleted.
redacted - whether or not the collected bundle will be redacted or unredacted

The builtin will return request_id, true if the request is generated successfully, or
null, false if creating a request for transaction fingerprint id that doesn't exist.
Existence of a transaction fingerprint id is determined by its existence in
`crdb_internal.transaction_statistics`. This is necessary because it is currently
the only system of record for transaction fingerprints in cockroachdb.

The user making the request for a transaction diagnostics bundle must have either
VIEWACTIVITY or VIEWACTIVITYREDACTED grants to call this builtin. If they have
VIEWACTIVITYREDACTED, only redacted bundles can be requested.

Resolves: CRDB-54322
Epic: CRDB-53541
Release note (sql change): adds a new builtin:
```
crdb_internal.request_transaction_bundle(
transaction_fingerprint_id: string,
sampling_probability: float,
min_execution_latency: interval,
expires_after: interval,
redacted: bool) -> (int as request_id, bool as created)
```

transaction_fingerprint_id - a hex-encoded fingerprint id for the transaction
                             intended to be captured
sampling_probability - the probability used to determine if a transaction bundle
                       should be recorded. This value must be between [0,1].
min_execution_latency - the minimum execution latency for a transaction. If the
                        execution time of a transaction is lower than this value,
                        the request will not be considered fulfilled and will remain
                        uncompleted. If sampling_probability is non-zero, this value
                        must also be non-zero.
expires_after - the duration in which a request will remain open. If zero is provided,
                the request will exist until it is completed or deleted.
redacted - whether or not the collected bundle will be redacted or unredacted

The built-in will return request_id, true if the request is generated successfully, or
null, false if creating a request for transaction fingerprint id that doesn't exist.

The user making the request for a transaction diagnostics bundle must have either
VIEWACTIVITY or VIEWACTIVITYREDACTED grants to call this builtin. If they have
VIEWACTIVITYREDACTED, only redacted bundles can be requested.
@kyle-a-wong
Copy link
Contributor Author

bors r+

@craig
Copy link
Contributor

craig bot commented Sep 24, 2025

@craig craig bot merged commit c8c2809 into cockroachdb:master Sep 24, 2025
23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants