(
name: string,
options?: {
readonly description?: string | undefined
readonly attributes?: Metric.Attributes | undefined
readonly preregisteredWords?: ReadonlyArray<string> | undefined
}
): FrequencyCreates a Frequency metric which can be used to count the number of
occurrences of a string.
When to use
Use when you need a metric for counting how often a specific event or incident occurs.
Details
The optional description describes the frequency, and attributes attach
dimensions to it. Use preregisteredWords to initialize occurrence counts
for known string values before updates arrive.
Example (Creating frequency metrics)
import { Data, Effect, Metric } from "effect"
class FrequencyError extends Data.TaggedError("FrequencyError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create a frequency metric for HTTP status codes
const statusFrequency = Metric.frequency("http_status_codes", {
description: "Frequency of HTTP response status codes",
preregisteredWords: ["200", "404", "500"] // Pre-register common codes
})
// Create a frequency metric for user actions
const userActionFrequency = Metric.frequency("user_actions", {
description: "Frequency of user actions performed",
attributes: { application: "web-app" }
})
// Create a frequency metric for error types
const errorTypeFrequency = Metric.frequency("error_types", {
description: "Frequency of different error types"
})
// Record different occurrences
yield* Metric.update(statusFrequency, "200") // Success response
yield* Metric.update(statusFrequency, "200") // Another success
yield* Metric.update(statusFrequency, "404") // Not found error
yield* Metric.update(statusFrequency, "500") // Server error
yield* Metric.update(statusFrequency, "200") // Another success
yield* Metric.update(userActionFrequency, "login")
yield* Metric.update(userActionFrequency, "view_dashboard")
yield* Metric.update(userActionFrequency, "login")
yield* Metric.update(userActionFrequency, "logout")
yield* Metric.update(errorTypeFrequency, "ValidationError")
yield* Metric.update(errorTypeFrequency, "NetworkError")
yield* Metric.update(errorTypeFrequency, "ValidationError")
// Get frequency counts
const statusCounts = yield* Metric.value(statusFrequency)
const actionCounts = yield* Metric.value(userActionFrequency)
const errorCounts = yield* Metric.value(errorTypeFrequency)
// statusCounts.occurrences will be:
// Map { "200" => 3, "404" => 1, "500" => 1 }
// actionCounts.occurrences will be:
// Map { "login" => 2, "view_dashboard" => 1, "logout" => 1 }
// errorCounts.occurrences will be:
// Map { "ValidationError" => 2, "NetworkError" => 1 }
return { statusCounts, actionCounts, errorCounts }
})constructors
Source effect/Metric.ts:23515 lines
export const const frequency: (
name: string,
options?: {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly preregisteredWords?:
| ReadonlyArray<string>
| undefined
}
) => Frequency
Creates a Frequency metric which can be used to count the number of
occurrences of a string.
When to use
Use when you need a metric for counting how often a specific event or
incident occurs.
Details
The optional description describes the frequency, and attributes attach
dimensions to it. Use preregisteredWords to initialize occurrence counts
for known string values before updates arrive.
Example (Creating frequency metrics)
import { Data, Effect, Metric } from "effect"
class FrequencyError extends Data.TaggedError("FrequencyError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Create a frequency metric for HTTP status codes
const statusFrequency = Metric.frequency("http_status_codes", {
description: "Frequency of HTTP response status codes",
preregisteredWords: ["200", "404", "500"] // Pre-register common codes
})
// Create a frequency metric for user actions
const userActionFrequency = Metric.frequency("user_actions", {
description: "Frequency of user actions performed",
attributes: { application: "web-app" }
})
// Create a frequency metric for error types
const errorTypeFrequency = Metric.frequency("error_types", {
description: "Frequency of different error types"
})
// Record different occurrences
yield* Metric.update(statusFrequency, "200") // Success response
yield* Metric.update(statusFrequency, "200") // Another success
yield* Metric.update(statusFrequency, "404") // Not found error
yield* Metric.update(statusFrequency, "500") // Server error
yield* Metric.update(statusFrequency, "200") // Another success
yield* Metric.update(userActionFrequency, "login")
yield* Metric.update(userActionFrequency, "view_dashboard")
yield* Metric.update(userActionFrequency, "login")
yield* Metric.update(userActionFrequency, "logout")
yield* Metric.update(errorTypeFrequency, "ValidationError")
yield* Metric.update(errorTypeFrequency, "NetworkError")
yield* Metric.update(errorTypeFrequency, "ValidationError")
// Get frequency counts
const statusCounts = yield* Metric.value(statusFrequency)
const actionCounts = yield* Metric.value(userActionFrequency)
const errorCounts = yield* Metric.value(errorTypeFrequency)
// statusCounts.occurrences will be:
// Map { "200" => 3, "404" => 1, "500" => 1 }
// actionCounts.occurrences will be:
// Map { "login" => 2, "view_dashboard" => 1, "logout" => 1 }
// errorCounts.occurrences will be:
// Map { "ValidationError" => 2, "NetworkError" => 1 }
return { statusCounts, actionCounts, errorCounts }
})
frequency = (name: stringname: string, options: | {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly preregisteredWords?:
| ReadonlyArray<string>
| undefined
}
| undefined
description?: string | undefineddescription?: string | undefined
readonly attributes?: Metric.Attributes | undefinedattributes?: Metric.type Metric<in Input, out State>.Attributes = Readonly<Record<string, string>> | readonly [string, string][]Union type for metric attributes that can be provided as either an object or array of tuples.
Example (Providing attributes in different formats)
import { Data, Effect, Metric } from "effect"
class AttributesError extends Data.TaggedError("AttributesError")<{
readonly operation: string
}> {}
const program = Effect.gen(function*() {
// Different ways to specify attributes
const attributesAsObject = {
service: "api",
environment: "production",
version: "1.2.3"
}
const attributesAsArray: ReadonlyArray<[string, string]> = [
["service", "api"],
["environment", "production"],
["version", "1.2.3"]
]
// Create metrics with different attribute formats
const requestCounter1 = Metric.counter("requests", {
description: "Total requests",
attributes: attributesAsObject // Using object format
})
const requestCounter2 = Metric.counter("requests", {
description: "Total requests",
attributes: attributesAsArray // Using array format
})
// Function to normalize attributes to object format
const normalizeAttributes = (
attrs: typeof attributesAsObject | ReadonlyArray<[string, string]>
) => {
if (Array.isArray(attrs)) {
return Object.fromEntries(attrs)
}
return attrs
}
// Add runtime attributes using withAttributes
const contextualCounter = Metric.withAttributes(requestCounter1, {
method: "GET",
endpoint: "/api/users"
})
// Update metrics with different attribute combinations
yield* Metric.update(contextualCounter, 1)
// Both formats result in the same internal representation
const normalizedObject = normalizeAttributes(attributesAsObject)
const normalizedArray = normalizeAttributes(attributesAsArray)
return {
attributeFormats: {
object: normalizedObject, // { service: "api", environment: "production", version: "1.2.3" }
array: normalizedArray, // { service: "api", environment: "production", version: "1.2.3" }
areEqual:
JSON.stringify(normalizedObject) === JSON.stringify(normalizedArray) // true
}
}
})
Attributes | undefined
readonly preregisteredWords?: readonly string[] | undefinedpreregisteredWords?: interface ReadonlyArray<T>ReadonlyArray<string> | undefined
}): Frequency => new constructor FrequencyMetric(id: string, options?: {
readonly description?: string | undefined;
readonly attributes?: Metric.Attributes | undefined;
readonly preregisteredWords?: ReadonlyArray<string> | undefined;
}): FrequencyMetric
name: stringname, options: | {
readonly description?: string | undefined
readonly attributes?:
| Metric.Attributes
| undefined
readonly preregisteredWords?:
| ReadonlyArray<string>
| undefined
}
| undefined