文档文档

Amazon Timestream 输出插件

此插件将指标写入Amazon Timestream 服务。

引入于: Telegraf v1.16.0 标签: cloud, datastore 操作系统支持: all

身份验证

此插件使用凭证链进行身份验证,以连接到 Timestream API 端点。插件将按以下顺序尝试进行身份验证。

  1. 通过 STS 的 Web 身份提供商凭证,如果指定了 role_arnweb_identity_token_file
  2. [通过 STS 假定的凭证] 如果指定了 role_arn 属性(源凭证将根据后续规则进行评估)。endpoint_url 属性仅用于 Timestream 服务。获取凭证时,将使用 STS 全局端点。
  3. 通过 STS 的 Web 身份提供商凭证,如果指定了 role_arnweb_identity_token_file
  4. 通过 STS 假定的凭证 如果指定了 role_arn 属性(源凭证将根据后续规则进行评估)。endpoint_url 属性仅用于 Timestream 服务。获取凭证时,将使用 STS 全局端点。
  5. 来自 access_keysecret_keytoken 属性的显式凭证
  6. 来自 profile 属性的共享配置文件
  7. 环境变量
  8. 共享凭证
  9. EC2 实例配置文件

全局配置选项

插件支持其他全局和插件配置设置,用于修改指标、标签和字段,创建别名以及配置插件顺序等任务。更多详情请参阅 CONFIGURATION.md

配置

# Configuration for sending metrics to Amazon Timestream.
[[outputs.timestream]]
  ## Amazon Region
  region = "us-east-1"

  ## Amazon Credentials
  ## Credentials are loaded in the following order:
  ## 1) Web identity provider credentials via STS if role_arn and
  ##    web_identity_token_file are specified
  ## 2) Assumed credentials via STS if role_arn is specified
  ## 3) explicit credentials from 'access_key' and 'secret_key'
  ## 4) shared profile from 'profile'
  ## 5) environment variables
  ## 6) shared credentials file
  ## 7) EC2 Instance Profile
  #access_key = ""
  #secret_key = ""
  #token = ""
  #role_arn = ""
  #web_identity_token_file = ""
  #role_session_name = ""
  #profile = ""
  #shared_credential_file = ""

  ## Endpoint to make request against, the correct endpoint is automatically
  ## determined and this option should only be set if you wish to override the
  ## default.
  ##   ex: endpoint_url = "https://:8000"
  # endpoint_url = ""

  ## Timestream database where the metrics will be inserted.
  ## The database must exist prior to starting Telegraf.
  database_name = "yourDatabaseNameHere"

  ## Specifies if the plugin should describe the Timestream database upon
  ## starting to validate if it has access, necessary permissions, connection,
  ## etc., as a safety check. If the describe operation fails, the plugin will
  ## not start and therefore the Telegraf agent will not start.
  describe_database_on_start = false

  ## Specifies how the data is organized in Timestream.
  ## Valid values are: single-table, multi-table.
  ## When mapping_mode is set to single-table, all of the data is stored in a
  ## single table. When mapping_mode is set to multi-table, the data is
  ## organized and stored in multiple tables. The default is multi-table.
  mapping_mode = "multi-table"

  ## Specifies if the plugin should create the table, if it doesn't exist.
  create_table_if_not_exists = true

  ## Specifies the Timestream table magnetic store retention period in days.
  ## Check Timestream documentation for more details.
  ## NOTE: This property is valid when create_table_if_not_exists = true.
  create_table_magnetic_store_retention_period_in_days = 365

  ## Specifies the Timestream table memory store retention period in hours.
  ## Check Timestream documentation for more details.
  ## NOTE: This property is valid when create_table_if_not_exists = true.
  create_table_memory_store_retention_period_in_hours = 24

  ## Specifies how the data is written into Timestream.
  ## Valid values are: true, false
  ## When use_multi_measure_records is set to true, all of the tags and fields
  ## are stored as a single row in a Timestream table.
  ## When use_multi_measure_record is set to false, Timestream stores each field
  ## in a separate table row, thereby storing the tags multiple times (once for
  ## each field). The recommended setting is true. The default is false.
  use_multi_measure_records = "false"

  ## Specifies the measure_name to use when sending multi-measure records.
  ## NOTE: This property is valid when use_multi_measure_records=true and
  ## mapping_mode=multi-table
  measure_name_for_multi_measure_records = "telegraf_measure"

  ## Specifies the name of the table to write data into
  ## NOTE: This property is valid when mapping_mode=single-table.
  # single_table_name = ""

  ## Specifies the name of dimension when all of the data is being stored in a
  ## single table and the measurement name is transformed into the dimension
  ## value (see Mapping data from Influx to Timestream for details)
  ## NOTE: This property is valid when mapping_mode=single-table.
  # single_table_dimension_name_for_telegraf_measurement_name = "namespace"

  ## Only valid and optional if create_table_if_not_exists = true
  ## Specifies the Timestream table tags.
  ## Check Timestream documentation for more details
  # create_table_tags = { "foo" = "bar", "environment" = "dev"}

  ## Specify the maximum number of parallel go routines to ingest/write data
  ## If not specified, defaulted to 1 go routines
  max_write_go_routines = 25

无符号整数

Timestream 不支持 无符号 int64 值。使用 uint64 的值,如果小于最大有符号 int64,将按预期返回。任何更大的值将被限制为最大 int64 值。

批处理

Timestream WriteInputRequest.CommonAttributes 用于将数据高效地写入 Timestream。

多线程

遵循通用插件设计模式,使用单个线程将数据写入 Timestream。

错误

如果尝试写入 Timestream 不支持的 Telegraf 字段类型,该字段将被丢弃,并向日志发出错误。

如果从 Timestream 接收到 ThrottlingException 或 InternalServerException,错误将返回给 Telegraf,在这种情况下,Telegraf 将把指标保留在缓冲区中,并在下次刷新时重试写入这些指标。

如果收到 ResourceNotFoundException

  • 如果 create_table_if_not_exists 配置设置为 true,插件将尝试创建适当的表,并在成功创建表后重新写入记录。
  • 如果 create_table_if_not_exists 配置设置为 false,记录将被丢弃,并向日志发出错误。

如果从 Timestream 收到任何其他 AWS 错误,记录将被丢弃,并向日志发出错误,因为重试此类请求很可能不会成功。

日志记录

在 Telegraf 中打开 debug 标志以启用详细日志记录(包括正在写入 Timestream 的记录)。

测试

使用以下命令执行单元测试

go test -v ./plugins/outputs/timestream/...

将 Influx 数据映射到 Timestream

当将数据从 Influx 写入 Timestream 时,默认情况下数据将按如下方式写入:

  1. 时间戳将作为 time 字段写入。
  2. Tag 将作为 dimension 写入。
  3. Field 将作为 measure 写入。
  4. Measurement 将作为表名写入。

例如,考虑以下行协议格式的数据

weather,location=us-midwest,season=summer temperature=82,humidity=71 1465839830100400200
airquality,location=us-west no2=5,pm25=16 1465839830100400200

其中:weatherairquality 是 measurement 名称,locationseason 是 tag,temperaturehumidityno2pm25 是 field。

当选择为每个 measurement 创建单独的表并在单个表行中存储多个 field 时,数据将写入 Timestream 如下:

  1. 该插件将创建两个表,即 weather 和 airquality(mapping_mode=multi-table)。

  2. 这些表可能包含单个表行中的多个 field(use_multi_measure_records=true)。

  3. weather 表将包含以下列和数据:

    timelocationseasonmeasure_nametemperaturehumidity
    2016-06-13 17:43:50us-midwestsummer<measure_name_for_multi_measure_records>8271
  4. airquality 表将包含以下列和数据:

    timelocationmeasure_nameno2pm25
    2016-06-13 17:43:50us-west<measure_name_for_multi_measure_records>516

注意:<measure_name_for_multi_measure_records> 代表该属性的实际值。

您也可以选择为每个 measurement 创建单独的表,并将每个 field 存储在每个表中的单独行中。在这种情况下:

  1. 该插件将创建两个表,即 weather 和 airquality(mapping_mode=multi-table)。

  2. 每个表行将只包含一个 field(use_multi_measure_records=false)。

  3. weather 表将包含以下列和数据:

    timelocationseasonmeasure_namemeasure_value::bigint
    2016-06-13 17:43:50us-midwestsummertemperature82
    2016-06-13 17:43:50us-midwestsummerhumidity71
  4. airquality 表将包含以下列和数据:

    timelocationmeasure_namemeasure_value::bigint
    2016-06-13 17:43:50us-westno25
    2016-06-13 17:43:50us-westpm2516

您也可以选择将所有 measurement 存储在单个表中,并将所有 field 存储在单个表行中。在这种情况下:

  1. 该插件将创建一个名为 <single_table_name> 的表(mapping_mode=single-table)。
  2. 该表可能包含单个表行中的多个 field(use_multi_measure_records=true)。
  3. 该表将包含以下列和数据:
    timelocationseason<single_table_dimension_name_for_telegraf_measurement_name>measure_nametemperaturehumidityno2pm25
    2016-06-13 17:43:50us-midwestsummerweather<measure_name_for_multi_measure_records>8271nullnull
    2016-06-13 17:43:50us-westnullairquality<measure_name_for_multi_measure_records>nullnull516

注意:<single_table_name> 代表该属性的实际值。<single_table_dimension_name_for_telegraf_measurement_name> 代表该属性的实际值。<measure_name_for_multi_measure_records> 代表该属性的实际值。

此外,您可以选择将所有 measurement 存储在单个表中,并将每个 field 存储在单独的表行中。在这种情况下:

  1. Timestream 将创建一个名为 <single_table_name> 的表(mapping_mode=single-table)。
  2. 每个表行将只包含一个 field(use_multi_measure_records=false)。
  3. 该表将包含以下列和数据:
    timelocationseasonnamespacemeasure_namemeasure_value::bigint
    2016-06-13 17:43:50us-midwestsummerweathertemperature82
    2016-06-13 17:43:50us-midwestsummerweatherhumidity71
    2016-06-13 17:43:50us-westNULLairqualityno25
    2016-06-13 17:43:50us-westNULLairqualitypm2516

注意:<single_table_name> 代表该属性的实际值。<single_table_dimension_name_for_telegraf_measurement_name> 代表该属性的实际值。<measure_name_for_multi_measure_records> 代表该属性的实际值。


此页面是否有帮助?

感谢您的反馈!


InfluxDB 3.8 新特性

InfluxDB 3.8 和 InfluxDB 3 Explorer 1.6 的主要增强功能。

查看博客文章

InfluxDB 3.8 现已适用于 Core 和 Enterprise 版本,同时发布了 InfluxDB 3 Explorer UI 的 1.6 版本。本次发布着重于操作成熟度,以及如何更轻松地部署、管理和可靠地运行 InfluxDB。

更多信息,请查看

InfluxDB Docker 的 latest 标签将指向 InfluxDB 3 Core

在 **2026 年 2 月 3 日**,InfluxDB Docker 镜像的 latest 标签将指向 InfluxDB 3 Core。为避免意外升级,请在您的 Docker 部署中使用特定的版本标签。

如果使用 Docker 来安装和运行 InfluxDB,latest 标签将指向 InfluxDB 3 Core。为避免意外升级,请在您的 Docker 部署中使用特定的版本标签。例如,如果使用 Docker 运行 InfluxDB v2,请将 latest 版本标签替换为 Docker pull 命令中的特定版本标签 — 例如

docker pull influxdb:2