github.com/google/fleetspeak@v0.1.15-0.20240426164851-4f31f62c1aea/fleetspeak/src/server/stats/collector.go (about)

     1  // Copyright 2017 Google Inc.
     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  //     https://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 a fleetspeak server.
    17  package stats
    18  
    19  import (
    20  	"context"
    21  	"time"
    22  
    23  	"github.com/google/fleetspeak/fleetspeak/src/common"
    24  	"github.com/google/fleetspeak/fleetspeak/src/server/db"
    25  
    26  	fspb "github.com/google/fleetspeak/fleetspeak/src/common/proto/fleetspeak"
    27  	mpb "github.com/google/fleetspeak/fleetspeak/src/common/proto/fleetspeak_monitoring"
    28  )
    29  
    30  // PollType indicates the type of poll, primarily differentiating between the
    31  // original bidirectional contact and the different events within a streaming
    32  // connection.
    33  type PollType int
    34  
    35  // PollType values.
    36  const (
    37  	FullPoll         PollType = iota // Classic one-off bidirectional poll.
    38  	StreamStart                      // Bidirectional poll that starts a streaming connection.
    39  	StreamFromClient                 // 'Poll' that is really a client pushing data to the server.
    40  	StreamToClient                   // 'Poll' that is really the server pushing data to the client.
    41  )
    42  
    43  // String implements fmt.Stringer.
    44  func (t PollType) String() string {
    45  	switch t {
    46  	case FullPoll:
    47  		return "POLL"
    48  	case StreamStart:
    49  		return "STREAM_START"
    50  	case StreamFromClient:
    51  		return "STREAM_FROM_CLIENT"
    52  	case StreamToClient:
    53  		return "STREAM_TO_CLIENT"
    54  	default:
    55  	}
    56  	return "UNKNOWN"
    57  }
    58  
    59  // A PollInfo describes a client poll operation which has occurred.
    60  type PollInfo struct {
    61  	// A Context associated with the poll operation, if available.
    62  	CTX context.Context
    63  
    64  	// The ClientID of the polling client, if available.
    65  	ID common.ClientID
    66  
    67  	// When the operation started and ended.
    68  	Start, End time.Time
    69  
    70  	// Http status code returned to the client.
    71  	Status int
    72  
    73  	// Bytes read and written.
    74  	ReadBytes, WriteBytes int
    75  
    76  	// Time spent reading and writing messages.
    77  	ReadTime, WriteTime time.Duration
    78  
    79  	// Whether the client was in the client cache.
    80  	CacheHit bool
    81  
    82  	// The 'type of poll.
    83  	Type PollType
    84  }
    85  
    86  // A Collector is a component which is notified when certain events occurred, to support
    87  // performance monitoring of a fleetspeak installation.
    88  type Collector interface {
    89  	// MessageIngested is called when a message is received from a client, or as
    90  	// a backlogged message from the datastore.
    91  	MessageIngested(backlogged bool, m *fspb.Message, cd *db.ClientData)
    92  
    93  	// MessageSaved is called when a message is first saved to the database.
    94  	// m.Data will have been set to nil for fully processed messages.
    95  	MessageSaved(forClient bool, m *fspb.Message, cd *db.ClientData)
    96  
    97  	// MessageProcessed is called when a message is successfully processed by the
    98  	// server.
    99  	MessageProcessed(start, end time.Time, m *fspb.Message, isFirstTry bool, cd *db.ClientData)
   100  
   101  	// MessageErrored is called when a message processing returned an error
   102  	// (temporary, or permanent).
   103  	MessageErrored(start, end time.Time, permanent bool, m *fspb.Message, isFirstTry bool, cd *db.ClientData)
   104  
   105  	// MessageDropped is called when a message has been dropped because too many
   106  	// messages for the services are being processed. Like a temporary error, the
   107  	// message will be retried after some minutes.
   108  	MessageDropped(m *fspb.Message, isFirstTry bool, cd *db.ClientData)
   109  
   110  	// ClientPoll is called every time a client polls the server.
   111  	ClientPoll(info PollInfo)
   112  
   113  	// DatastoreOperation is called every time a database operation completes.
   114  	DatastoreOperation(start, end time.Time, operation string, result error)
   115  
   116  	// ResourceUsageDataReceived is called every time a client-resource-usage proto is received.
   117  	ResourceUsageDataReceived(cd *db.ClientData, rud *mpb.ResourceUsageData, v *fspb.ValidationInfo)
   118  
   119  	// KillNotificationReceived is called when a kill notification is received from a client.
   120  	KillNotificationReceived(cd *db.ClientData, kn *mpb.KillNotification)
   121  }