Observability

Wait Events

PostgreSQL 17+ supports custom wait events for extensions. pgcollection registers the following events, enabling detailed monitoring via pg_stat_activity. On PostgreSQL 14–16, all events appear as Extension:extension.

Wait Event Description
CollectionCalculatingFlatSize Calculating the flat format size before a context switch
CollectionFlatten Converting to flat format for a context switch
CollectionExpand Expanding flat format to the optimized in-memory format
CollectionCast Casting to or from a type-modified collection
CollectionAdd Adding an item
CollectionCount Counting items
CollectionFind Finding an item by key
CollectionDelete Deleting an item
CollectionSort Sorting by keys
CollectionCopy Copying a collection
CollectionValue Returning the value at the current iterator position
CollectionToTable Converting to a table result set
CollectionFetch Fetching an item via subscript
CollectionAssign Assigning an item via subscript
CollectionInput Parsing JSON input into the expanded format
CollectionOutput Serializing to JSON string output

Both collection and icollection share the same wait events.

Usage Statistics

The collection_stats view provides per-session operation counters for both collection and icollection:

Column Description
add Number of add/assign operations
context_switch Number of times a collection switched memory contexts
delete Number of delete operations
find Number of find/fetch operations
sort Number of sort operations
exist Number of exist checks 
SELECT * FROM collection_stats;

Use collection_stats_reset() to clear the counters:

SELECT collection_stats_reset();