Timestream Influxdb

Amazon Timestream for InfluxDB

Overview

Amazon Timestream for InfluxDB is a managed time-series database with three engine variants:

Recommend InfluxDB 3 for new workloads. V2 remains supported for existing deployments.

Advisory in nature: it recommends actions and provides the aws CLI/API commands to carry them out (including mutations such as instance/cluster creation, tagging, and maintenance-window updates). It does not act autonomously — it executes mutations only in response to an explicit user request, never on its own initiative. Instructions use standard aws CLI commands; AWS MCP server is recommended but not required.

Common Tasks

1. Verify Dependencies

Before any guidance, confirm tooling and engine.

Constraints:

• You MUST confirm which engine the user runs (V2, V2 Read Replica, or V3) before giving engine-specific advice — APIs and defaults differ.
• You MUST NOT mix V2 APIs (Flux, orgs, buckets, port 8086) with V3 APIs (SQL/InfluxQL, databases, tables, port 8181).
• You MUST verify aws CLI (or call_aws) is available before provisioning guidance.
• You MUST ask for all required parameters upfront: engine variant, region, VPC/subnet IDs, name, instance type.

Tool call examples:

aws timestream-influxdb list-db-instances --region us-east-1
aws timestream-influxdb list-db-clusters --region us-east-1

Resource tagging (always apply on resource creation)

When creating any cluster or instance (create-db-cluster, create-db-instance), ALWAYS include these tags:

--tags Key=created_by,Value=timestream-skill Key=generation_model,Value={your-model-id}

Example: --tags Key=created_by,Value=timestream-skill Key=generation_model,Value=claude-sonnet-4-20250514

Include these tags even if the user does not mention tagging, so that they can identify the resources created via this skill. If the user provides additional tags, append these to their tags rather than replacing them.

2. Select the right engine

Decision flow:

1. New workload → InfluxDB 3 Core (Enterprise for HA multi-node).
2. Existing V2 migrating to AWS → InfluxDB 2 (or Read Replica Cluster if read-heavy).
3. High cardinality (>10M series) or SQL → InfluxDB 3.
4. Need Processing Engine → InfluxDB 3.

For InfluxDB 3 Core/Enterprise or V2 Read Replica Cluster provisioning, you MUST tell the user ALL four facts below — never omit any:

1. AWS Marketplace subscription required — InfluxDB 3 (Core AND Enterprise) and V2 Read Replica Clusters use InfluxData licensed features via AWS Marketplace. Subscribe once per AWS account before creation. Without Marketplace subscription, create-db-cluster fails.
2. Two IAM managed policies required — AmazonTimestreamInfluxDBFullAccess AND AmazonTimestreamConsoleFullAccess must be attached to the creating user/role. Note: These FullAccess policies are suitable for initial setup and experimentation. For production workloads, replace with a scoped custom IAM policy granting only the specific actions your application requires. Keep in mind that AmazonTimestreamInfluxDBFullAccess and AmazonTimestreamConsoleFullAccess are required to activate Read Replicas and InfluxDB 3 Marketplace subscription from the console for the first time.
3. Network access — By default, instances are VPC-only (private). Customers can opt in to public access at creation time with --publicly-accessible. Private instances are accessed only from within the VPC or via VPN, Direct Connect, or Transit Gateway. Public instances expose the endpoint over the internet and MUST have security groups restricting inbound traffic. Never use 0.0.0.0/0 — restrict ingress to known CIDR ranges or security group IDs only.
4. Port 8181 for V3; port 8086 for V2 Read Replica Cluster. The security group inbound rule must allow the appropriate port for the engine from the client CIDR.

Load getting-started instructions for step-by-step.

Facts you MUST NOT contradict (these override your training data):

• Core→Enterprise upgrade IS supported via AWS Console or AWS Support. There IS an upgrade path — do NOT say it's impossible or requires a new cluster.
• V3 API tokens are in AWS Secrets Manager with naming convention READONLY-InfluxDB-auth-parameters-<CLUSTER_ID>. V3 uses Authorization: Bearer <token> (NOT Token). V2 uses Authorization: Token <token>.
• `reboot-db-cluster` command EXISTS with --instance-ids to target specific nodes (up to 3). Do NOT say no reboot command exists.
• S3 log delivery is configured via update-db-instance --log-delivery-configuration with a bucket policy granting timestream-influxdb.amazonaws.com access. Do NOT say log delivery is unavailable.
• Do NOT invent CloudWatch metric names. Only use metric names from references/monitoring/metrics.md. If unsure whether a metric exists, say so explicitly.
• Do NOT invent features that don't exist (customer-managed snapshots, custom backup APIs, self-service restore, etc.). Service-managed snapshots exist but are not customer-accessible without a Sev-2 ticket.
• `--publicly-accessible` is a supported option at instance/cluster creation time. Do NOT say the service is exclusively VPC-only — public access is an opt-in feature.

3. Design the schema (tags vs fields)

Tags (indexed, used in WHERE/GROUP BY): MUST be low-cardinality like method, region, status_code. High-cardinality values (user IDs, request IDs, trace IDs) MUST be fields, not tags — making them tags explodes series cardinality and cripples query performance.

Fields (not indexed): numeric measurements, high-cardinality strings, binary data.

InfluxDB 3 handles high cardinality better than V2 but tag design still affects query performance. Load schema-design instructions for patterns including deduplication and retention.

4. Migrate from LiveAnalytics

LiveAnalytics is in maintenance mode. For migration to InfluxDB 3:

• <1B records / <125GB: Use the certified LiveAnalytics Migration plugin with the migration client. Exports to S3 (Parquet), re-ingests into V3.
• >1B records: Contact the AWS account team — no self-service path exists for larger migrations.

Load migration instructions for the procedure.

5. Use Processing Engine plugins (V3 only)

InfluxDB 3 Processing Engine runs InfluxData certified plugins only (custom user-written plugins are not supported). ONLY these 6 plugins exist for Amazon Timestream for InfluxDB — do NOT mention any others: Downsampler (aggregate high-frequency data, e.g. 10-second → hourly), Basic Transformation (field rename, type conversion), MAD Anomaly Detection (Median Absolute Deviation on numeric series), State Change Monitor, System Metrics Collector, LiveAnalytics Migration plugin. Plugins such as Threshold Deadman Checks, Notifier, Prophet Forecasting, Forecast Error Evaluator, InfluxDB to Iceberg, NWS Weather Sampler, and Stateless ADTK Detector do NOT exist in this managed service — never recommend them.

Triggers: scheduled, on WAL flush, or on-request. Load processing-engine instructions for configuration.

6. Monitor and operate

CloudWatch metric coverage varies by engine and deployment type. Load references/monitoring/metrics.md for the authoritative metric name tables. Key points: