Attributes and Aliasing

Attributes and Aliasing

Overview

Centralizing logs from various technologies and applications can generate tens or hundreds of different attributes in a Log Management environment, especially when many teams are working within the same environment.

For instance, a client IP may have various log attributes: clientIP, client_ip_address, remote_address, client.ip, etc. The execution time of a request may be referred to as exec_time, request_latency, request.time_elapsed, etc.

Use attributes and aliasing to unify your Logs environment.

Attribute types and aliasing

Attributes prescribe logs facets and tags, which are used for filtering and searching in Log Explorer.

  • Reserved attributes are automatically ingested.

  • Standard attributes are the backbone of the naming convention for your organization. There is a default set of standard attributes available in the app. However, this list can be customized to create a naming convention for your team.

  • Use Aliasing once you’ve implemented a naming convention with standard attributes or if you’re trying to create a unique standard facet from multiple log sources. For example, follow the clients most impacted by latencies on a hybrid Apache and Amazon Cloud Front infrastructure, using the standard Network Client IP facet alongside the standard duration. Aliasing allows implementation of a naming convention without having to change a team’s technical stack.

Reserved attributes

Below is a list of reserved attributes that are automatically ingested with logs:

Note: If you’re also collecting traces or metrics, it is recommended to configure unified service tagging. This configuration ties Datadog telemetry together through the use of three standard tags: env, service, and version. Refer to the dedicated unified service tagging documentation for more information.

AttributeDescription
hostThe name of the originating host as defined in metrics. Datadog automatically retrieves corresponding host tags from the matching host in Datadog and applies them to your logs. The Agent sets this value automatically.
sourceThis corresponds to the integration name: the technology from which the log originated. When it matches an integration name, Datadog automatically installs the corresponding parsers and facets. For example: nginx, postgresql, etc.
statusThis corresponds to the level/severity of a log. It is used to define patterns and has a dedicated layout in the Datadog Log UI.
serviceThe name of the application or service generating the log events. It is used to switch from Logs to APM, so make sure you define the same value when you use both products.
trace_idThis corresponds to the Trace ID used for traces. It is used to correlate your log with its trace.
messageBy default, Datadog ingests the value of the message attribute as the body of the log entry. That value is then highlighted and displayed in Live Tail, where it is indexed for full text search.

Standard attributes

Log integrations natively rely on a default set of standard attributes.

Admin users in your organization can curate the list:

  • From the Log Explorer: Promote existing attributes as standard attributes.
  • From the standard attribute configuration page: Create new standard attributes.

The standard attribute table comes with a set of predefined standard attributes. You can append that list with your own attributes, and edit or delete existing standard attributes:

A standard attribute is defined by its:

  • Path: The path of the attribute promoted as a standard attribute, as you would find it in your JSON (for example: network.client.ip).
  • Type (string, integer, double, boolean): The type of the attribute, which is used to cast elements of the remapping list.
  • Aliasing list: Comma separated list of attributes that should be aliased to it.
  • Description: Human readable description of the attribute.

The standard attribute panel appears when you add a new standard attribute or edit an existing one:

Default standard attribute list

The default standard attribute list is split into the functional domains:

Network

The following attributes are related to the data used in network communication. All fields and metrics are prefixed by network.

FullnameTypeDescription
network.client.ipstringThe IP address of the client that initiated the TCP connection.
network.destination.ipstringThe IP address the client connected to.
network.client.portnumberThe port of the client that initiated the connection.
network.destination.portnumberThe TCP port the client connected to.
network.bytes_readnumberTotal number of bytes transmitted from the client to the server when the log is emitted.
network.bytes_writtennumberTotal number of bytes transmitted from the server to the client when the log is emitted.

Typical integrations relying on these attributes include Apache, Varnish, AWS ELB, Nginx, HAProxy, etc.

Geolocation

The following attributes are related to the geolocation of IP addresses used in network communication. All fields are prefixed by network.client.geoip or network.destination.geoip.

FullnameTypeDescription
network.client.geoip.country.namestringName of the country
network.client.geoip.country.iso_codestringISO Code of the country (example: US for the United States, FR for France)
network.client.geoip.continent.codestringISO code of the continent (EU, AS, NA, AF, AN, SA, OC)
network.client.geoip.continent.namestringName of the continent (Europe, Australia, North America, Africa, Antartica, South America, Oceania)
network.client.geoip.subdivision.namestringName of the first subdivision level of the country (example: California in the United States or the Sarthe department in France)
network.client.geoip.subdivision.iso_codestringISO Code of the first subdivision level of the country (example: CA in the United States or the SA department in France)
network.client.geoip.city.nameStringThe name of the city (example Paris, New York)

HTTP requests

These attributes are related to the data commonly used in HTTP requests and accesses. All attributes are prefixed by http.

Typical integrations relying on these attributes include Apache, Rails, AWS CloudFront, web applications servers, etc.

Common attributes
FullnameTypeDescription
http.urlstringThe URL of the HTTP request.
http.status_codenumberThe HTTP response status code.
http.methodstringIndicates the desired action to be performed for a given resource.
http.refererstringHTTP header field that identifies the address of the webpage that linked to the resource being requested.
http.request_idstringThe ID of the HTTP request.
http.useragentstringThe User-Agent as it is sent (raw format). See below for more details.
http.versionstringThe version of HTTP used for the request.
URL details attributes

These attributes provide details about the parsed parts of the HTTP URL. They are generally generated thanks to the URL parser. All attributes are prefixed by http.url_details.

FullnameTypeDescription
http.url_details.hoststringThe HTTP host part of the URL.
http.url_details.portnumberThe HTTP port part of the URL.
http.url_details.pathstringThe HTTP path part of the URL.
http.url_details.queryStringobjectThe HTTP query string parts of the URL decomposed as query params key/value attributes.
http.url_details.schemestringThe protocol name of the URL (HTTP or HTTPS)
User-Agent attributes

These attributes provide details about the meanings of user-agents' attributes. They are generally generated thanks to the User-Agent parser. All attributes are prefixed by http.useragent_details.

FullnameTypeDescription
http.useragent_details.os.familystringThe OS family reported by the User-Agent.
http.useragent_details.browser.familystringThe Browser Family reported by the User-Agent.
http.useragent_details.device.familystringThe Device family reported by the User-Agent.

Source code

These attributes are related to the data used when a log or an error is generated via a logger in a custom application. All attributes are prefixed either by logger or error.

FullnameTypeDescription
logger.namestringThe name of the logger.
logger.thread_namestringThe name of the current thread when the log is fired.
logger.method_namestringThe class method name.
logger.versionstringThe version of the logger.
error.kindstringThe error type or kind (or code is some cases).
error.messagestringA concise, human-readable, one-line message explaining the event
error.stackstringThe stack trace or the complementary information about the error

Typical integrations relying on these attributes are: Java, NodeJs, .NET, Golang, Python, etc.

Database

Database related attributes are prefixed by db.

FullnameTypeDescription
db.instancestringDatabase instance name. E.g., in Java, if jdbc.url="jdbc:mysql://127.0.0.1:3306/customers", the instance name is customers.
db.statementstringA database statement for the given database type. E.g., for mySQL: "SELECT * FROM wuser_table"; for Redis: "SET mykey 'WuValue'".
db.operationstringThe operation that was performed (“query”, “update”, “delete”,…).
db.userstringUser that performs the operation.

Typical integrations relying on these attributes are: Cassandra, MySQL, RDS, Elasticsearch, etc.

Performance

Performance metrics attributes.

FullnameTypeDescription
durationnumberA duration of any kind in nanoseconds: HTTP response time, database query time, latency, etc.

Datadog advises you to remap any durations within your logs on this attribute since Datadog displays and uses it as a default measure for trace search.

All attributes and measures are prefixed by usr.

FullnameTypeDescription
usr.idstringThe user identifier.
usr.namestringThe user friendly name.
usr.emailstringThe user email.

Syslog and log shippers

These attributes are related to the data added by a syslog or a log-shipper agent. All fields and metrics are prefixed by syslog.

FullnameTypeDescription
syslog.hostnamestringThe hostname
syslog.appnamestringThe application name. Generally remapped to the service reserved attribute.
syslog.severitynumberThe log severity. Generally remapped to the status reserved attribute.
syslog.timestampstringThe log timestamp. Generally remapped to the date reserved attribute.
syslog.envstringThe environment name where the source of logs come from.

Some integrations that rely on these are: Rsyslog, NxLog, Syslog-ng, Fluentd, Logstash, etc.

DNS

All attributes and measures are prefixed by dns.

FullnameTypeDescription
dns.idstringThe DNS query identifier.
dns.question.namestringThe queried domain name.
dns.question.typestringA two octet code which specifies the DNS question type.
dns.question.classstringThe class looked up by the DNS question (i.e IN when using the internet).
dns.question.sizenumberThe DNS question size in bytes.
dns.answer.namestringThe IP address that the DNS answers with.
dns.answer.typestringA two octet code which specifies the DNS answer type.
dns.answer.classstringThe class answered by the DNS.
dns.answer.sizenumberThe DNS answer size in bytes.
dns.flags.rcodestringThe DNS reply code.

Events

All attributes are prefixed by evt.

FullnameTypeDescription
evt.namestringThe shared name across events generated by the same activity (e.g.: authentication).
evt.outcomestringThe result of the event (e.g. success, failure).

Aliasing

Creating an alias for a source attribute that maps to a destination attribute allows logs to carry both the source and destination attributes.

Users can interact with either the aliased (source) or standard (destination) faceted attribute. However, users are encouraged to use the standard facet rather than the aliased one. This provides guidance towards the naming convention, and discourages users from building assets (such as saved views or dashboards) based on non-standard content.

Additional details regarding aliasing:

  • Aliasing happens after logs are processed by pipelines. Any extracted or processed attribute can be used as a source for aliasing.
  • Datadog enforces the type of an aliased attribute. If this is not possible, the aliasing is skipped.
  • In the case of a log that already carries the destination attribute, aliasing overrides the value of that log.
  • For a standard attribute to which multiple attributes are aliased, if a log carries several of these source attributes, only one of these source attributes is aliased.
  • Any updates or additions to standard attributes are only applied to newly ingested logs.
  • Standard attributes cannot be aliased.
  • Attributes can only be aliased to standard attributes.
  • To respect the JSON structure of logs, it is not possible to have one standard attribute as the child of another (for example user and user.name cannot both be standard attributes).

See the associated documentation for additional information.

Further Reading