Documentation for ProfileEvents (draft) #3010

dbms/src/Common/ProfileEvents.cpp

@@ -5,176 +5,175 @@
 
 /// Available events. Add something here as you wish.
 #define APPLY_FOR_EVENTS(M) \
-    M(Query) \
-    M(SelectQuery) \
-    M(InsertQuery) \
-    M(FileOpen) \
-    M(FileOpenFailed) \
-    M(Seek) \
-    M(ReadBufferFromFileDescriptorRead) \
-    M(ReadBufferFromFileDescriptorReadFailed) \
-    M(ReadBufferFromFileDescriptorReadBytes) \
-    M(WriteBufferFromFileDescriptorWrite) \
-    M(WriteBufferFromFileDescriptorWriteFailed) \
-    M(WriteBufferFromFileDescriptorWriteBytes) \
-    M(ReadBufferAIORead) \
-    M(ReadBufferAIOReadBytes) \
-    M(WriteBufferAIOWrite) \
-    M(WriteBufferAIOWriteBytes) \
-    M(ReadCompressedBytes) \
-    M(CompressedReadBufferBlocks) \
-    M(CompressedReadBufferBytes) \
-    M(UncompressedCacheHits) \
-    M(UncompressedCacheMisses) \
-    M(UncompressedCacheWeightLost) \
-    M(IOBufferAllocs) \
-    M(IOBufferAllocBytes) \
-    M(ArenaAllocChunks) \
-    M(ArenaAllocBytes) \
-    M(FunctionExecute) \
-    M(TableFunctionExecute) \
-    M(MarkCacheHits) \
-    M(MarkCacheMisses) \
-    M(CreatedReadBufferOrdinary) \
-    M(CreatedReadBufferAIO) \
-    M(CreatedWriteBufferOrdinary) \
-    M(CreatedWriteBufferAIO) \
-    M(DiskReadElapsedMicroseconds) \
-    M(DiskWriteElapsedMicroseconds) \
-    M(NetworkReceiveElapsedMicroseconds) \
-    M(NetworkSendElapsedMicroseconds) \
-    M(ThrottlerSleepMicroseconds) \
-    \
-    M(ReplicatedPartFetches) \
-    M(ReplicatedPartFailedFetches) \
-    M(ObsoleteReplicatedParts) \
-    M(ReplicatedPartMerges) \
-    M(ReplicatedPartFetchesOfMerged) \
-    M(ReplicatedPartMutations) \
-    M(ReplicatedPartChecks) \
-    M(ReplicatedPartChecksFailed) \
-    M(ReplicatedDataLoss) \
-    \
-    M(InsertedRows) \
-    M(InsertedBytes) \
-    M(DelayedInserts) \
-    M(RejectedInserts) \
-    M(DelayedInsertsMilliseconds) \
-    M(DuplicatedInsertedBlocks) \
-    \
-    M(ZooKeeperInit) \
-    M(ZooKeeperTransactions) \
-    M(ZooKeeperList) \
-    M(ZooKeeperCreate) \
-    M(ZooKeeperRemove) \
-    M(ZooKeeperExists) \
-    M(ZooKeeperGet) \
-    M(ZooKeeperSet) \
-    M(ZooKeeperMulti) \
-    M(ZooKeeperCheck) \
-    M(ZooKeeperClose) \
-    M(ZooKeeperWatchResponse) \
-    M(ZooKeeperUserExceptions) \
-    M(ZooKeeperHardwareExceptions) \
-    M(ZooKeeperOtherExceptions) \
-    M(ZooKeeperWaitMicroseconds) \
-    M(ZooKeeperBytesSent) \
-    M(ZooKeeperBytesReceived) \
-    \
-    M(DistributedConnectionFailTry) \
-    M(DistributedConnectionMissingTable) \
-    M(DistributedConnectionStaleReplica) \
-    M(DistributedConnectionFailAtAll) \
-    \
-    M(CompileAttempt) \
-    M(CompileSuccess) \
-    \
-    M(CompileFunction) \
-    \
-    M(ExternalSortWritePart) \
-    M(ExternalSortMerge) \
-    M(ExternalAggregationWritePart) \
-    M(ExternalAggregationMerge) \
-    M(ExternalAggregationCompressedBytes) \
-    M(ExternalAggregationUncompressedBytes) \
-    \
-    M(SlowRead) \
-    M(ReadBackoff) \
-    \
-    M(ReplicaYieldLeadership) \
-    M(ReplicaPartialShutdown) \
-    \
-    M(SelectedParts) \
-    M(SelectedRanges) \
-    M(SelectedMarks) \
-    \
-    M(MergedRows) \
-    M(MergedUncompressedBytes) \
-    M(MergesTimeMilliseconds)\
-    \
-    M(MergeTreeDataWriterRows) \
-    M(MergeTreeDataWriterUncompressedBytes) \
-    M(MergeTreeDataWriterCompressedBytes) \
-    M(MergeTreeDataWriterBlocks) \
-    M(MergeTreeDataWriterBlocksAlreadySorted) \
-    \
-    M(ObsoleteEphemeralNode) \
-    M(CannotRemoveEphemeralNode) \
-    M(LeaderElectionAcquiredLeadership) \
-    \
-    M(RegexpCreated) \
-    M(ContextLock) \
-    \
-    M(StorageBufferFlush) \
-    M(StorageBufferErrorOnFlush) \
-    M(StorageBufferPassedAllMinThresholds) \
-    M(StorageBufferPassedTimeMaxThreshold) \
-    M(StorageBufferPassedRowsMaxThreshold) \
-    M(StorageBufferPassedBytesMaxThreshold) \
-    \
-    M(DictCacheKeysRequested) \
-    M(DictCacheKeysRequestedMiss) \
-    M(DictCacheKeysRequestedFound) \
-    M(DictCacheKeysExpired) \
-    M(DictCacheKeysNotFound) \
-    M(DictCacheKeysHit) \
-    M(DictCacheRequestTimeNs) \
-    M(DictCacheRequests) \
-    M(DictCacheLockWriteNs) \
-    M(DictCacheLockReadNs) \
-    \
-    M(DistributedSyncInsertionTimeoutExceeded) \
-    M(DataAfterMergeDiffersFromReplica) \
-    M(DataAfterMutationDiffersFromReplica) \
-    M(PolygonsAddedToPool) \
-    M(PolygonsInPoolAllocatedBytes) \
-    M(RWLockAcquiredReadLocks) \
-    M(RWLockAcquiredWriteLocks) \
-    M(RWLockReadersWaitMilliseconds) \
-    M(RWLockWritersWaitMilliseconds) \
-    M(NetworkErrors) \
-    \
-    M(RealTimeMicroseconds) \
-    M(UserTimeMicroseconds) \
-    M(SystemTimeMicroseconds) \
-    M(SoftPageFaults) \
-    M(HardPageFaults) \
-    M(VoluntaryContextSwitches) \
-    M(InvoluntaryContextSwitches) \
-    \
-    M(OSIOWaitMicroseconds) \
-    M(OSCPUWaitMicroseconds) \
-    M(OSCPUVirtualTimeMicroseconds) \
-    M(OSReadBytes) \
-    M(OSWriteBytes) \
-    M(OSReadChars) \
-    M(OSWriteChars) \
+    M(Query, "Number of queries started to be interpreted and maybe executed. Does not include queries that are failed to parse, that are rejected due to AST size limits; rejected due to quota limits or limits on number of simultaneously running queries. May include internal queries initiated by ClickHouse itself. Does not count subqueries.") \
+    M(SelectQuery, "Same as Query, but only for SELECT queries.") \
+    M(InsertQuery, "Same as Query, but only for INSERT queries.") \
+    M(FileOpen, "Number of files opened.") \
+    M(Seek, "Number of times the 'lseek' function was called.") \
+    M(ReadBufferFromFileDescriptorRead, "Number of reads (read/pread) from a file descriptor. Does not include sockets.") \
+    M(ReadBufferFromFileDescriptorReadFailed, "Number of times the read (read/pread) from a file descriptor have failed.") \
+    M(ReadBufferFromFileDescriptorReadBytes, "Number of bytes read from file descriptors. If the file is compressed, this will show compressed data size.") \
+    M(WriteBufferFromFileDescriptorWrite, "Number of writes (write/pwrite) to a file descriptor. Does not include sockets.") \
+    M(WriteBufferFromFileDescriptorWriteFailed, "Number of times the write (write/pwrite) to a file descriptor have failed.") \
+    M(WriteBufferFromFileDescriptorWriteBytes, "Number of bytes written to file descriptors. If the file is compressed, this will show compressed data size.") \
+    M(ReadBufferAIORead, "") \
+    M(ReadBufferAIOReadBytes, "") \
+    M(WriteBufferAIOWrite, "") \
+    M(WriteBufferAIOWriteBytes, "") \
+    M(ReadCompressedBytes, "") \
+    M(CompressedReadBufferBlocks, "") \
+    M(CompressedReadBufferBytes, "") \
+    M(UncompressedCacheHits, "") \
+    M(UncompressedCacheMisses, "") \
+    M(UncompressedCacheWeightLost, "") \
+    M(IOBufferAllocs, "") \
+    M(IOBufferAllocBytes, "") \
+    M(ArenaAllocChunks, "") \
+    M(ArenaAllocBytes, "") \
+    M(FunctionExecute, "") \
+    M(TableFunctionExecute, "") \
+    M(MarkCacheHits, "") \
+    M(MarkCacheMisses, "") \
+    M(CreatedReadBufferOrdinary, "") \
+    M(CreatedReadBufferAIO, "") \
+    M(CreatedWriteBufferOrdinary, "") \
+    M(CreatedWriteBufferAIO, "") \
+    M(DiskReadElapsedMicroseconds, "") \
+    M(DiskWriteElapsedMicroseconds, "") \
+    M(NetworkReceiveElapsedMicroseconds, "") \
+    M(NetworkSendElapsedMicroseconds, "") \
+    M(ThrottlerSleepMicroseconds, "") \
+    \
+    M(ReplicatedPartFetches, "") \
+    M(ReplicatedPartFailedFetches, "") \
+    M(ObsoleteReplicatedParts, "") \
+    M(ReplicatedPartMerges, "") \
+    M(ReplicatedPartFetchesOfMerged, "") \
+    M(ReplicatedPartMutations, "") \
+    M(ReplicatedPartChecks, "") \
+    M(ReplicatedPartChecksFailed, "") \
+    M(ReplicatedDataLoss, "") \
+    \
+    M(InsertedRows, "") \
+    M(InsertedBytes, "") \
+    M(DelayedInserts, "") \
+    M(RejectedInserts, "") \
+    M(DelayedInsertsMilliseconds, "") \
+    M(DuplicatedInsertedBlocks, "") \
+    \
+    M(ZooKeeperInit, "") \
+    M(ZooKeeperTransactions, "") \
+    M(ZooKeeperList, "") \
+    M(ZooKeeperCreate, "") \
+    M(ZooKeeperRemove, "") \
+    M(ZooKeeperExists, "") \
+    M(ZooKeeperGet, "") \
+    M(ZooKeeperSet, "") \
+    M(ZooKeeperMulti, "") \
+    M(ZooKeeperCheck, "") \
+    M(ZooKeeperClose, "") \
+    M(ZooKeeperWatchResponse, "") \
+    M(ZooKeeperUserExceptions, "") \
+    M(ZooKeeperHardwareExceptions, "") \
+    M(ZooKeeperOtherExceptions, "") \
+    M(ZooKeeperWaitMicroseconds, "") \
+    M(ZooKeeperBytesSent, "") \
+    M(ZooKeeperBytesReceived, "") \
+    \
+    M(DistributedConnectionFailTry, "") \
+    M(DistributedConnectionMissingTable, "") \
+    M(DistributedConnectionStaleReplica, "") \
+    M(DistributedConnectionFailAtAll, "") \
+    \
+    M(CompileAttempt, "") \
+    M(CompileSuccess, "") \
+    \
+    M(CompileFunction, "") \
+    \
+    M(ExternalSortWritePart, "") \
+    M(ExternalSortMerge, "") \
+    M(ExternalAggregationWritePart, "") \
+    M(ExternalAggregationMerge, "") \
+    M(ExternalAggregationCompressedBytes, "") \
+    M(ExternalAggregationUncompressedBytes, "") \
+    \
+    M(SlowRead, "") \
+    M(ReadBackoff, "") \
+    \
+    M(ReplicaYieldLeadership, "") \
+    M(ReplicaPartialShutdown, "") \
+    \
+    M(SelectedParts, "") \
+    M(SelectedRanges, "") \
+    M(SelectedMarks, "") \
+    \
+    M(MergedRows, "") \
+    M(MergedUncompressedBytes, "") \
+    M(MergesTimeMilliseconds, "")\
+    \
+    M(MergeTreeDataWriterRows, "") \
+    M(MergeTreeDataWriterUncompressedBytes, "") \
+    M(MergeTreeDataWriterCompressedBytes, "") \
+    M(MergeTreeDataWriterBlocks, "") \
+    M(MergeTreeDataWriterBlocksAlreadySorted, "") \
+    \
+    M(ObsoleteEphemeralNode, "") \
+    M(CannotRemoveEphemeralNode, "") \
+    M(LeaderElectionAcquiredLeadership, "") \
+    \
+    M(RegexpCreated, "") \
+    M(ContextLock, "") \
+    \
+    M(StorageBufferFlush, "") \
+    M(StorageBufferErrorOnFlush, "") \
+    M(StorageBufferPassedAllMinThresholds, "") \
+    M(StorageBufferPassedTimeMaxThreshold, "") \
+    M(StorageBufferPassedRowsMaxThreshold, "") \
+    M(StorageBufferPassedBytesMaxThreshold, "") \
+    \
+    M(DictCacheKeysRequested, "") \
+    M(DictCacheKeysRequestedMiss, "") \
+    M(DictCacheKeysRequestedFound, "") \
+    M(DictCacheKeysExpired, "") \
+    M(DictCacheKeysNotFound, "") \
+    M(DictCacheKeysHit, "") \
+    M(DictCacheRequestTimeNs, "") \
+    M(DictCacheRequests, "") \
+    M(DictCacheLockWriteNs, "") \
+    M(DictCacheLockReadNs, "") \
+    \
+    M(DistributedSyncInsertionTimeoutExceeded, "") \
+    M(DataAfterMergeDiffersFromReplica, "") \
+    M(DataAfterMutationDiffersFromReplica, "") \
+    M(PolygonsAddedToPool, "") \
+    M(PolygonsInPoolAllocatedBytes, "") \
+    M(RWLockAcquiredReadLocks, "") \
+    M(RWLockAcquiredWriteLocks, "") \
+    M(RWLockReadersWaitMilliseconds, "") \
+    M(RWLockWritersWaitMilliseconds, "") \
+    M(NetworkErrors, "") \
+    \
+    M(RealTimeMicroseconds, "") \
+    M(UserTimeMicroseconds, "") \
+    M(SystemTimeMicroseconds, "") \
+    M(SoftPageFaults, "") \
+    M(HardPageFaults, "") \
+    M(VoluntaryContextSwitches, "") \
+    M(InvoluntaryContextSwitches, "") \
+    \
+    M(OSIOWaitMicroseconds, "") \
+    M(OSCPUWaitMicroseconds, "") \
+    M(OSCPUVirtualTimeMicroseconds, "") \
+    M(OSReadBytes, "") \
+    M(OSWriteBytes, "") \
+    M(OSReadChars, "") \
+    M(OSWriteChars, "") \
 
 
 namespace ProfileEvents
 {
 
-#define M(NAME) extern const Event NAME = __COUNTER__;
+#define M(NAME, DOCUMENTATION) extern const Event NAME = __COUNTER__;
     APPLY_FOR_EVENTS(M)
 #undef M
 constexpr Event END = __COUNTER__;