github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/ts/resolution.go (about)

     1  // Copyright 2014 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  package ts
    12  
    13  import (
    14  	"fmt"
    15  	"time"
    16  )
    17  
    18  // Resolution is used to enumerate the different resolution values supported by
    19  // Cockroach.
    20  type Resolution int64
    21  
    22  func (r Resolution) String() string {
    23  	switch r {
    24  	case Resolution10s:
    25  		return "10s"
    26  	case Resolution30m:
    27  		return "30m"
    28  	case resolution1ns:
    29  		return "1ns"
    30  	case resolution50ns:
    31  		return "50ns"
    32  	case resolutionInvalid:
    33  		return "BAD"
    34  	}
    35  	return fmt.Sprintf("%d", r)
    36  }
    37  
    38  // Resolution enumeration values are directly serialized and persisted into
    39  // system keys; these values must never be altered or reordered. If new rollup
    40  // resolutions are added, the IsRollup() method must be modified as well.
    41  const (
    42  	// Resolution10s stores data with a sample resolution of 10 seconds.
    43  	Resolution10s Resolution = 1
    44  	// Resolution30m stores roll-up data from a higher resolution at a sample
    45  	// resolution of 30 minutes.
    46  	Resolution30m Resolution = 2
    47  	// resolution1ns stores data with a sample resolution of 1 nanosecond. Used
    48  	// only for testing.
    49  	resolution1ns Resolution = 998
    50  	// resolution50ns stores roll-up data from the 1ns resolution at a sample
    51  	// resolution of 50 nanoseconds. Used for testing.
    52  	resolution50ns Resolution = 999
    53  	// resolutionInvalid is an invalid resolution used only for testing. It causes
    54  	// an error to be thrown in certain methods. It is invalid because its sample
    55  	// period is not a divisor of its slab period.
    56  	resolutionInvalid Resolution = 1000
    57  )
    58  
    59  // sampleDurationByResolution is a map used to retrieve the sample duration
    60  // corresponding to a Resolution value. Sample durations are expressed in
    61  // nanoseconds.
    62  var sampleDurationByResolution = map[Resolution]int64{
    63  	Resolution10s:     int64(time.Second * 10),
    64  	Resolution30m:     int64(time.Minute * 30),
    65  	resolution1ns:     1,  // 1ns resolution only for tests.
    66  	resolution50ns:    50, // 50ns rollup only for tests.
    67  	resolutionInvalid: 10, // Invalid resolution.
    68  }
    69  
    70  // slabDurationByResolution is a map used to retrieve the slab duration
    71  // corresponding to a Resolution value; the slab duration determines how many
    72  // samples are stored at a single Cockroach key/value. Slab durations are
    73  // expressed in nanoseconds.
    74  var slabDurationByResolution = map[Resolution]int64{
    75  	Resolution10s:     int64(time.Hour),
    76  	Resolution30m:     int64(time.Hour * 24),
    77  	resolution1ns:     10,   // 1ns resolution only for tests.
    78  	resolution50ns:    1000, // 50ns rollup only for tests.
    79  	resolutionInvalid: 11,
    80  }
    81  
    82  // SampleDuration returns the sample duration corresponding to this resolution
    83  // value, expressed in nanoseconds.
    84  func (r Resolution) SampleDuration() int64 {
    85  	duration, ok := sampleDurationByResolution[r]
    86  	if !ok {
    87  		panic(fmt.Sprintf("no sample duration found for resolution value %v", r))
    88  	}
    89  	return duration
    90  }
    91  
    92  // SlabDuration returns the slab duration corresponding to this resolution
    93  // value, expressed in nanoseconds. The slab duration determines how many
    94  // consecutive samples are stored in a single Cockroach key/value.
    95  func (r Resolution) SlabDuration() int64 {
    96  	duration, ok := slabDurationByResolution[r]
    97  	if !ok {
    98  		panic(fmt.Sprintf("no slab duration found for resolution value %v", r))
    99  	}
   100  	return duration
   101  }
   102  
   103  // IsRollup returns true if this resolution contains rollup data: statistical
   104  // values about a large number of samples taken over a long period, such as
   105  // the min, max and sum.
   106  func (r Resolution) IsRollup() bool {
   107  	return r == Resolution30m || r == resolution50ns
   108  }
   109  
   110  // TargetRollupResolution returns a target resolution that data from this
   111  // resolution should be rolled up into in lieu of deletion. For example,
   112  // Resolution10s has a target rollup resolution of Resolution30m.
   113  func (r Resolution) TargetRollupResolution() (Resolution, bool) {
   114  	switch r {
   115  	case Resolution10s:
   116  		return Resolution30m, true
   117  	case resolution1ns:
   118  		return resolution50ns, true
   119  	}
   120  	return r, false
   121  }
   122  
   123  func normalizeToPeriod(timestampNanos int64, period int64) int64 {
   124  	return timestampNanos - timestampNanos%period
   125  }
   126  
   127  func (r Resolution) normalizeToSlab(timestampNanos int64) int64 {
   128  	return normalizeToPeriod(timestampNanos, r.SlabDuration())
   129  }