| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
OpenTelemetry.Logs.Core
Synopsis
- data LoggerProvider = LoggerProvider {}
- data LoggerProviderOptions = LoggerProviderOptions {}
- emptyLoggerProviderOptions :: LoggerProviderOptions
- createLoggerProvider :: [LogRecordProcessor] -> LoggerProviderOptions -> LoggerProvider
- setGlobalLoggerProvider :: MonadIO m => LoggerProvider -> m ()
- getGlobalLoggerProvider :: MonadIO m => m LoggerProvider
- shutdownLoggerProvider :: MonadIO m => LoggerProvider -> m ()
- forceFlushLoggerProvider :: MonadIO m => LoggerProvider -> Maybe Int -> m FlushResult
- data InstrumentationLibrary = InstrumentationLibrary {}
- data Logger = Logger {}
- makeLogger :: LoggerProvider -> InstrumentationLibrary -> Logger
- data ReadableLogRecord
- data ReadWriteLogRecord
- class IsReadableLogRecord r where
- class IsReadableLogRecord r => IsReadWriteLogRecord r where
- readLogRecordAttributeLimits :: r -> AttributeLimits
- modifyLogRecord :: r -> (ImmutableLogRecord -> ImmutableLogRecord) -> IO ()
- atomicModifyLogRecord :: r -> (ImmutableLogRecord -> (ImmutableLogRecord, b)) -> IO b
- data LogRecordArguments = LogRecordArguments {}
- data AnyValue
- class ToValue a where
- data SeverityNumber
- toShortName :: SeverityNumber -> Maybe Text
- emitLogRecord :: MonadIO m => Logger -> LogRecordArguments -> m ReadWriteLogRecord
- addAttribute :: (IsReadWriteLogRecord r, MonadIO m, ToValue a) => r -> Text -> a -> m ()
- addAttributes :: (IsReadWriteLogRecord r, MonadIO m, ToValue a) => r -> HashMap Text a -> m ()
- logRecordGetAttributes :: (IsReadableLogRecord r, MonadIO m) => r -> m LogAttributes
LoggerProvider operations
data LoggerProvider Source #
Loggers can be created from LoggerProviders
Constructors
| LoggerProvider | |
Fields
| |
data LoggerProviderOptions Source #
emptyLoggerProviderOptions :: LoggerProviderOptions Source #
Options for creating a LoggerProvider with no resources and default limits.
In effect, logging is a no-op when using this configuration and no-op Processors.
createLoggerProvider :: [LogRecordProcessor] -> LoggerProviderOptions -> LoggerProvider Source #
Initialize a new LoggerProvider
You should generally use getGlobalLoggerProvider for most applications.
setGlobalLoggerProvider :: MonadIO m => LoggerProvider -> m () Source #
Overwrite the globally configured LoggerProvider.
Loggers acquired from the previously installed LoggerProviders
will continue to use that LoggerProviders settings.
getGlobalLoggerProvider :: MonadIO m => m LoggerProvider Source #
Access the globally configured LoggerProvider. This LoggerProvider is no-op until initialized by the SDK
shutdownLoggerProvider :: MonadIO m => LoggerProvider -> m () Source #
This method provides a way for provider to do any cleanup required.
This will also trigger shutdowns on all internal processors.
forceFlushLoggerProvider Source #
Arguments
| :: MonadIO m | |
| => LoggerProvider | |
| -> Maybe Int | Optional timeout in microseconds, defaults to 5,000,000 (5s) |
| -> m FlushResult | Result that denotes whether the flush action succeeded, failed, or timed out. |
This method provides a way for provider to immediately export all LogRecords that have not yet
been exported for all the internal processors.
Logger operations
data InstrumentationLibrary Source #
An identifier for the library that provides the instrumentation for a given Instrumented Library. Instrumented Library and Instrumentation Library may be the same library if it has built-in OpenTelemetry instrumentation.
The inspiration of the OpenTelemetry project is to make every library and application observable out of the box by having them call OpenTelemetry API directly. However, many libraries will not have such integration, and as such there is a need for a separate library which would inject such calls, using mechanisms such as wrapping interfaces, subscribing to library-specific callbacks, or translating existing telemetry into the OpenTelemetry model.
A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.
An instrumentation library should be named to follow any naming conventions of the instrumented library (e.g. middleware for a web framework).
If there is no established name, the recommendation is to prefix packages with "hs-opentelemetry-instrumentation", followed by the instrumented library name itself.
In general, the simplest way to get the instrumentation library is to use detectInstrumentationLibrary, which uses the Haskell package name and version.
Constructors
| InstrumentationLibrary | |
Fields
| |
Instances
LogRecords can be created from Loggers. Loggers are uniquely identified by the libraryName, libraryVersion, schemaUrl fields of InstrumentationLibrary.
Creating two Loggers with the same identity but different libraryAttributes is a user error.
Constructors
| Logger | |
Fields
| |
Arguments
| :: LoggerProvider | The |
| -> InstrumentationLibrary | The library that the |
| -> Logger |
LogRecord operations
data ReadableLogRecord Source #
Instances
data ReadWriteLogRecord Source #
This is a data type that can represent logs from various sources: application log files, machine generated events, system logs, etc. Specification outlined here. Existing log formats can be unambiguously mapped to this data type. Reverse mapping from this data type is also possible to the extent that the target log format has equivalent capabilities. Uses an IORef under the hood to allow mutability.
Instances
class IsReadableLogRecord r where Source #
This is a typeclass representing LogRecords that can be read from.
A function receiving this as an argument MUST be able to access all the information added to the LogRecord. It MUST also be able to access the Instrumentation Scope and Resource information (implicitly) associated with the LogRecord.
The trace context fields MUST be populated from the resolved Context (either the explicitly passed Context or the current Context) when emitted.
Counts for attributes due to collection limits MUST be available for exporters to report as described in the transformation to non-OTLP formats specification.
Methods
readLogRecord :: r -> IO ImmutableLogRecord Source #
Reads the current state of the LogRecord from its internal IORef. The implementation mirrors readIORef.
readLogRecordInstrumentationScope :: r -> InstrumentationLibrary Source #
Reads the InstrumentationScope from the Logger that emitted the LogRecord
readLogRecordResource :: r -> MaterializedResources Source #
Reads the Resource from the LoggerProvider that emitted the LogRecord
class IsReadableLogRecord r => IsReadWriteLogRecord r where Source #
This is a typeclass representing LogRecords that can be read from or written to. All ReadWriteLogRecords are ReadableLogRecords.
A function receiving this as an argument MUST additionally be able to modify the following information added to the LogRecord:
- Timestamp
- ObservedTimestamp
- SeverityText
- SeverityNumber
- Body
- Attributes (addition, modification, removal)
- TraceId
- SpanId
- TraceFlags
Methods
readLogRecordAttributeLimits :: r -> AttributeLimits Source #
Reads the attribute limits from the LoggerProvider that emitted the LogRecord. These are needed to add more attributes.
modifyLogRecord :: r -> (ImmutableLogRecord -> ImmutableLogRecord) -> IO () Source #
Modifies the LogRecord using its internal IORef. This is lazy and is not an atomic operation. The implementation mirrors modifyIORef.
atomicModifyLogRecord :: r -> (ImmutableLogRecord -> (ImmutableLogRecord, b)) -> IO b Source #
An atomic version of modifyLogRecord. This function is lazy. The implementation mirrors atomicModifyIORef.
Instances
| IsReadWriteLogRecord ReadWriteLogRecord Source # | |
Defined in OpenTelemetry.Internal.Logs.Types Methods readLogRecordAttributeLimits :: ReadWriteLogRecord -> AttributeLimits Source # modifyLogRecord :: ReadWriteLogRecord -> (ImmutableLogRecord -> ImmutableLogRecord) -> IO () Source # atomicModifyLogRecord :: ReadWriteLogRecord -> (ImmutableLogRecord -> (ImmutableLogRecord, b)) -> IO b Source # | |
data LogRecordArguments Source #
Arguments that may be set on LogRecord creation. If observedTimestamp is not set, it will default to the current timestamp.
If context is not specified it will default to the current context. Refer to the documentation of LogRecord for descriptions
of the fields.
Constructors
| LogRecordArguments | |
Fields | |
An attribute represents user-provided metadata about a span, link, or event.
Any values are used in place of 'Standard Attributes' in logs because third-party
logs may not conform to the 'Standard Attribute' format.
Telemetry tools may use this data to support high-cardinality querying, visualization in waterfall diagrams, trace sampling decisions, and more.
Constructors
| TextValue Text | |
| BoolValue Bool | |
| DoubleValue Double | |
| IntValue Int64 | |
| ByteStringValue ByteString | |
| ArrayValue [AnyValue] | |
| HashMapValue (HashMap Text AnyValue) | |
| NullValue |
Instances
class ToValue a where Source #
Convert a Haskell value to an Any value.
data Foo = Foo instance ToValue Foo where toValue Foo = TextValue Foo
Instances
| ToValue Int64 Source # | |
| ToValue ByteString Source # | |
Defined in OpenTelemetry.Internal.Common.Types Methods toValue :: ByteString -> AnyValue Source # | |
| ToValue AnyValue Source # | |
| ToValue Text Source # | |
| ToValue Bool Source # | |
| ToValue Double Source # | |
| ToValue a => ToValue [a] Source # | |
Defined in OpenTelemetry.Internal.Common.Types | |
| ToValue a => ToValue (HashMap Text a) Source # | |
data SeverityNumber Source #
Constructors
| Trace | |
| Trace2 | |
| Trace3 | |
| Trace4 | |
| Debug | |
| Debug2 | |
| Debug3 | |
| Debug4 | |
| Info | |
| Info2 | |
| Info3 | |
| Info4 | |
| Warn | |
| Warn2 | |
| Warn3 | |
| Warn4 | |
| Error | |
| Error2 | |
| Error3 | |
| Error4 | |
| Fatal | |
| Fatal2 | |
| Fatal3 | |
| Fatal4 | |
| Unknown !Int |
Instances
toShortName :: SeverityNumber -> Maybe Text Source #
emitLogRecord :: MonadIO m => Logger -> LogRecordArguments -> m ReadWriteLogRecord Source #
Emits a LogRecord with properties specified by the passed in Logger and LogRecordArguments.
If observedTimestamp is not set in LogRecordArguments, it will default to the current timestamp.
If context is not specified in LogRecordArguments it will default to the current context.
The emitted LogRecord will be passed to any LogRecordProcessors registered on the LoggerProvider
that created the Logger.
addAttribute :: (IsReadWriteLogRecord r, MonadIO m, ToValue a) => r -> Text -> a -> m () Source #
Add an attribute to a LogRecord.
This is not an atomic modification
As an application developer when you need to record an attribute first consult existing semantic conventions for Resources, Spans, and Metrics. If an appropriate name does not exists you will need to come up with a new name. To do that consider a few options:
The name is specific to your company and may be possibly used outside the company as well. To avoid clashes with names introduced by other companies (in a distributed system that uses applications from multiple vendors) it is recommended to prefix the new name by your company’s reverse domain name, e.g. 'com.acme.shopname'.
The name is specific to your application that will be used internally only. If you already have an internal company process that helps you to ensure no name clashes happen then feel free to follow it. Otherwise it is recommended to prefix the attribute name by your application name, provided that the application name is reasonably unique within your organization (e.g. 'myuniquemapapp.longitude' is likely fine). Make sure the application name does not clash with an existing semantic convention namespace.
The name may be generally applicable to applications in the industry. In that case consider submitting a proposal to this specification to add a new name to the semantic conventions, and if necessary also to add a new namespace.
It is recommended to limit names to printable Basic Latin characters (more precisely to 'U+0021' .. 'U+007E' subset of Unicode code points), although the Haskell OpenTelemetry specification DOES provide full Unicode support.
Attribute names that start with 'otel.' are reserved to be defined by OpenTelemetry specification. These are typically used to express OpenTelemetry concepts in formats that don’t have a corresponding concept.
For example, the 'otel.library.name' attribute is used to record the instrumentation library name, which is an OpenTelemetry concept that is natively represented in OTLP, but does not have an equivalent in other telemetry formats and protocols.
Any additions to the 'otel.*' namespace MUST be approved as part of OpenTelemetry specification.
addAttributes :: (IsReadWriteLogRecord r, MonadIO m, ToValue a) => r -> HashMap Text a -> m () Source #
A convenience function related to addAttribute that adds multiple attributes to a LogRecord at the same time.
This function may be slightly more performant than repeatedly calling addAttribute.
This is not an atomic modification
logRecordGetAttributes :: (IsReadableLogRecord r, MonadIO m) => r -> m LogAttributes Source #
This can be useful for pulling data for attributes and using it to copy / otherwise use the data to further enrich instrumentation.