github.com/google/osv-scalibr@v0.4.1/stats/collector.go (about)

     1  // Copyright 2025 Google LLC
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package stats contains interfaces and utilities relating to the collection of
    16  // statistics from Scalibr.
    17  package stats
    18  
    19  import (
    20  	"time"
    21  
    22  	"github.com/google/osv-scalibr/plugin"
    23  )
    24  
    25  // Collector is a component which is notified when certain events occur. It can be implemented with
    26  // different metric backends to enable monitoring of Scalibr.
    27  type Collector interface {
    28  	AfterInodeVisited(path string)
    29  	AfterExtractorRun(pluginName string, extractorstats *AfterExtractorStats)
    30  	AfterDetectorRun(name string, runtime time.Duration, err error)
    31  	AfterScan(runtime time.Duration, status *plugin.ScanStatus)
    32  
    33  	// AfterResultsExported is called after results have been exported. destination should merely be
    34  	// a category of where the result was written to (e.g. 'file', 'http'), not the precise location.
    35  	AfterResultsExported(destination string, bytes int, err error)
    36  
    37  	// AfterFileRequired may be called by individual plugins after the
    38  	// `FileRequired` method is called on a file. This allows plugins to report
    39  	// why a certain file may have been skipped. Note that in general, extractor
    40  	// plugins will not record a metric if a file was skipped because it is deemed
    41  	// completely irrelevant (e.g. the Python extractor will not report that it
    42  	// skipped a JAR file).
    43  	AfterFileRequired(pluginName string, filestats *FileRequiredStats)
    44  
    45  	// AfterFileExtracted may be called by individual plugins after a file was seen in
    46  	// the `Extract` method, as opposed to `AfterExtractorRun`, which is called by
    47  	// the filesystem handling code. This allows plugins to report internal state
    48  	// for metric collection.
    49  	AfterFileExtracted(pluginName string, filestats *FileExtractedStats)
    50  
    51  	// MaxRSS is called when the scan is finished. It is used to report the maximum resident
    52  	// memory usage of the scan.
    53  	MaxRSS(maxRSS int64)
    54  }
    55  
    56  // NoopCollector implements Collector by doing nothing.
    57  type NoopCollector struct{}
    58  
    59  // AfterInodeVisited implements Collector by doing nothing.
    60  func (c NoopCollector) AfterInodeVisited(path string) {}
    61  
    62  // AfterExtractorRun implements Collector by doing nothing.
    63  func (c NoopCollector) AfterExtractorRun(pluginName string, extractorstats *AfterExtractorStats) {}
    64  
    65  // AfterDetectorRun implements Collector by doing nothing.
    66  func (c NoopCollector) AfterDetectorRun(name string, runtime time.Duration, err error) {}
    67  
    68  // AfterScan implements Collector by doing nothing.
    69  func (c NoopCollector) AfterScan(runtime time.Duration, status *plugin.ScanStatus) {}
    70  
    71  // AfterResultsExported implements Collector by doing nothing.
    72  func (c NoopCollector) AfterResultsExported(destination string, bytes int, err error) {}
    73  
    74  // AfterFileRequired implements Collector by doing nothing.
    75  func (c NoopCollector) AfterFileRequired(pluginName string, filestats *FileRequiredStats) {}
    76  
    77  // AfterFileExtracted implements Collector by doing nothing.
    78  func (c NoopCollector) AfterFileExtracted(pluginName string, filestats *FileExtractedStats) {}
    79  
    80  // MaxRSS implements Collector by doing nothing.
    81  func (c NoopCollector) MaxRSS(maxRSS int64) {}