Distribution

Distribution 包含值母體的摘要統計資料。其中可選擇性包含直方圖，代表這些值在一組值區中的分布情形。

摘要統計資料包括值母體的計數、平均值、與平均值的平方差總和、最小值和最大值。直方圖是以一系列值區為基礎，並提供落入每個值區的值計數。值區的界限可明確指定，也可以透過公式計算固定或指數遞增寬度的值區。

雖然不禁止，但一般來說，在值母體中納入非有限值 (無限或 NaN) 是個壞主意，因為這會使 mean 和 sumOfSquaredDeviation 欄位變得毫無意義。

JSON 表示法 
{
  "count": string,
  "mean": number,
  "sumOfSquaredDeviation": number,
  "range": {
    object (Range)
  },
  "bucketOptions": {
    object (BucketOptions)
  },
  "bucketCounts": [
    string
  ],
  "exemplars": [
    {
      object (Exemplar)
    }
  ]
}
欄位
count

string (int64 format)

母體中的值數量。必須為非負數。如果提供直方圖，這個值必須等於 bucketCounts 中的值總和。
mean

number

母體中值的算術平均數。如果 count 為零，這個欄位就必須為零。
sumOfSquaredDeviation

number

母體中各值與平均值偏差的平方和。對於值 x_i，這是：

Sum[i=1..n]((x_i - mean)^2)

Knuth 撰寫的「The Art of Computer Programming」第 2 卷第 232 頁 (第 3 版) 說明瞭 Welford 的方法，可一次累加這個總和。

如果 count 為零，這個欄位就必須為零。
range

object (Range)

如果指定，則包含母體值範圍。如果 count 為零，則不得出現此欄位。
bucketOptions

object (BucketOptions)

定義直方圖值區界線。如果發布內容不含直方圖，請略過這個欄位。
bucketCounts[]

string (int64 format)

直方圖每個值區中的值數量，如 bucketOptions 所述。如果分配情形沒有直方圖，請省略這個欄位。如有直方圖，則 bucketCounts 中的值總和必須等於分配情形 count 欄位中的值。

如有提供，bucketCounts 應包含 N 個值，其中 N 是 bucketOptions 中指定的 bucket 數量。如果提供的數值少於 N 個，系統會假設剩餘值為 0。

bucketCounts 中的值順序會遵循三種值區類型所述的值區編號配置。第一個值必須是欠位值區的計數 (數字 0)。接下來的 N-2 個值是有限值區的計數 (數字 1 到 N-2)。bucketCounts 中的第 N 個值是溢位值區 (數字 N-1) 的計數。
exemplars[]

object (Exemplar)

必須依 value 欄位遞增排序。

範圍

母體值的範圍。

JSON 表示法 
{
  "min": number,
  "max": number
}
欄位
min

number

母體值的最小值。
max

number

母體值的最大值。

BucketOptions

BucketOptions 說明用於建立分布直方圖的 bucket 邊界。值區可以是線性序列、指數序列，也可以明確指定每個值區。BucketOptions 不包含每個值區中的值數量。

值區的下限值 (含) 和上限值 (不含) 之間的值，都會計入該值區。值區上限必須嚴格大於下限。分布的 N 個值區序列包含一個欠位值區 (編號 0)、零或多個有限值區 (編號 1 到 N - 2)，以及一個溢位值區 (編號 N - 1)。值區是連續的：值區 i (i > 0) 的下限與值區 i - 1 的上限相同。這些值區涵蓋整個有限值範圍：欠位值區的下限為負無限大，溢位值區的上限為正無限大。有限值區之所以稱為有限，是因為上下限都是有限值。

JSON 表示法 
{

  // Union field options can be only one of the following:
  "linearBuckets": {
    object (Linear)
  },
  "exponentialBuckets": {
    object (Exponential)
  },
  "explicitBuckets": {
    object (Explicit)
  }
  // End of list of possible types for union field options.
}
欄位
聯集欄位 options。必須設定這三個欄位中的其中一個。options 只能是下列其中一個設定：
linearBuckets

object (Linear)

線性 bucket。
exponentialBuckets

object (Exponential)

指數值區。
explicitBuckets

object (Explicit)

明確 bucket。

線性

指定線性序列的 bucket，這些 bucket 的寬度都相同 (溢位和下溢除外)。每個 bucket 代表 bucket 中特定值的常數絕對不確定度。

共有 numFiniteBuckets + 2 (= N) 個值區。值區 i 的邊界如下：

上限 (0 <= i < N-1)：offset + (width * i)。

下限 (1 <= i < N)：offset + (width * (i - 1))。

JSON 表示法 
{
  "numFiniteBuckets": integer,
  "width": number,
  "offset": number
}
欄位
numFiniteBuckets

integer

必須大於 0。
width

number

必須大於 0。
offset

number

第一個特徵分塊的下限。

指數

指定範圍的指數序列，其寬度與下限值成正比。每個範圍代表範圍內特定值的恆定相對不確定度。

共有 numFiniteBuckets + 2 (= N) 個值區。值區 i 的邊界如下：

上限 (0 <= i < N-1)：scale * (growthFactor ^ i)。

下限 (1 <= i < N)：scale * (growthFactor ^ (i - 1))。

JSON 表示法 
{
  "numFiniteBuckets": integer,
  "growthFactor": number,
  "scale": number
}
欄位
numFiniteBuckets

integer

必須大於 0。
growthFactor

number

必須大於 1。
scale

number

必須大於 0。

明確

指定一組任意寬度的 bucket。

共有 size(bounds) + 1 (= N) 個值區。值區 i 的邊界如下：

上限 (0 <= i < N-1)：bounds[i] 下限 (1 <= i < N)：bounds[i - 1]

bounds 欄位必須包含至少一個元素。如果 bounds 只有一個元素，則沒有有限值區，而該單一元素是溢位和欠位值區的共同界線。

JSON 表示法 
{
  "bounds": [
    number
  ]
}
欄位
bounds[]

number

值必須單調遞增。

範例

範例點可用於註解匯總的分布值。這類中繼資料會提供加入 Distribution 值區的特定值相關資訊，例如加入值時處於活動狀態的追蹤 ID。範例點可能包含其他資訊，例如範例值和時間戳記、來源等。

JSON 表示法 
{
  "value": number,
  "timestamp": string,
  "attachments": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
欄位
value

number

範例點的值。這個值會決定範例所屬的值區。
timestamp

string (Timestamp format)

上述值的觀察 (取樣) 時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
attachments[]

object

範例值的背景資訊。例如：

追蹤：type.googleapis.com/google.monitoring.v3.SpanContext

字串常值：type.googleapis.com/google.protobuf.StringValue

在彙整期間捨棄的標籤：type.googleapis.com/google.monitoring.v3.DroppedLabels

單一範例中，每種訊息類型只能有一個附件，系統會強制執行這項規定。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。