Amazon Timestream for LiveAnalytics와 유사한 기능을 원하는 경우 Amazon Timestream for InfluxDB를 고려해 보세요. 간소화된 데이터 수집과 실시간 분석을 위한 10밀리초 미만의 쿼리 응답 시간을 제공합니다. [여기](https://docs.aws.amazon.com//timestream/latest/developerguide/timestream-for-influxdb.html)에서 자세히 알아보세요.
기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Timestream for InfluxDB 3 클러스터에 데이터 쓰기
Amazon Timestream for InfluxDB 3는 시계열 데이터를 효율적으로 수집할 수 있는 강력한 기능을 제공합니다. 데이터를 올바르게 쓰는 방법을 이해하는 것은 성능을 극대화하고 데이터 무결성을 보장하는 데 필수적입니다.
Timestream for InfluxDB 3는 시계열 데이터를 작성하기 위한 여러 HTTP API 엔드포인트를 제공하여 다양한 통합 방법에 대한 유연성과 기존 InfluxDB 워크로드와의 호환성을 제공합니다.
## 라인 프로토콜 개요
InfluxDB 3는 높은 쓰기 처리량을 위해 설계되었으며 [라인 프로토콜](https://docs.influxdata.com/influxdb3/core/reference/line-protocol/)이라는 효율적이고 사람이 읽을 수 있는 쓰기 구문을 사용합니다. 스키마 온 라이트 데이터베이스인 InfluxDB는 수동 설정 없이 데이터 쓰기를 시작할 때 자동으로 논리적 데이터베이스, 테이블 및 해당 스키마를 생성합니다. 스키마가 생성되면 InfluxDB는 새로운 데이터를 수락하기 전에 향후 쓰기 요청을 해당 스키마에 대해 검증합니다. 동시에 요구 사항이 변경됨에 따라 스키마 진화를 허용합니다.
### 라인 프로토콜 구조
라인 프로토콜은 다음과 같은 필수 요소로 구성됩니다.
+ **테이블**: 데이터가 저장될 테이블의 문자열 식별자입니다.
+ (선택 사항) **태그 세트**: 메타데이터(인덱싱됨)를 나타내는 쉼표로 구분된 키-값 페어입니다.
+ **필드 세트**: 실제 측정값을 나타내는 쉼표로 구분된 키-값 페어입니다.
+ (선택 사항) **타임스탬프**: 데이터 포인트와 관련된 Unix 타임스탬프이며, 나노초 단위의 정밀도를 갖습니다.
필드 값은 다음 데이터 유형 중 하나일 수 있습니다.
+ String(따옴표로 묶어야 함)
+ Float(예: 23.4)
+ Integer(예: 10i)
+ Unsigned integer(예: 10u)
+ Boolean(true/false)
라인 프로토콜은 다음 일반 구문을 따릅니다.
```
myTable,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000
```
라인 프로토콜을 사용한 예제 데이터 포인트:
```
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
```
이 예제 'home' 테이블에 다음과 같은 데이터 포인트를 생성합니다.
+ 태그: room="Living Room"
+ 필드: temp=21.1(float), hum=35.9(float), co=0(integer)
+ 타임스탬프: 1735545600(Unix 초)
## API 엔드포인트 개요
InfluxDB 3는 세 가지 프라이머리 쓰기 엔드포인트를 지원합니다.
1. **기본 v3 API**(`/api/v3/write_lp`): 새 구현에 권장되는 엔드포인트입니다.
1. **v2 호환성 API**(`/api/v2/write`): InfluxDB v2.x 워크로드 마이그레이션용입니다.
1. **v1 호환성 API**(`/write`): InfluxDB v1.x 워크로드 마이그레이션용입니다.
### 기본 v3 쓰기 API 사용
`/api/v3/write_lp` 엔드포인트는 라인 프로토콜 데이터를 쓰기 위한 InfluxDB 3의 기본 API입니다.
요청 형식:
```
POST /api/v3/write_lp?db=DATABASE_NAME&precision=PRECISION&accept_partial=BOOLEAN&no_sync=BOOLEAN
```
쿼리 파라미터:
| **파라미터** | **설명** | **기본값** |
| --- | --- | --- |
| db | 데이터베이스 이름(필수) | - |
| precision | 타임스탬프 정밀도(ns, us, ms, s) | 자동 탐지됨 |
| accept\_partial | 오류에 대한 부분 쓰기 허용 | true |
| no\_sync | WAL 지속성 전 승인 | false |
####
쓰기 요청 예:
```
curl -v "https://your-cluster-endpoint:8086/api/v3/write_lp?db=sensors&precision=s" \
--header "Authorization: Bearer YOUR_TOKEN" \
--data-raw "home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1735545600
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1735545600"
```
### 쓰기 응답 모드
표준 모드(`no_sync`=false)
+ 승인하기 전에 WAL(Write-Ahead Log)에 데이터가 작성될 때까지 기다립니다.
+ 내구성 보증을 제공합니다.
+ WAL 지속성 대기로 인해 지연 시간이 늘어납니다.
+ 내구성이 필수적인 중요한 데이터에 권장됩니다.
빠른 모드(`no_sync`=true)
+ WAL 지속성을 기다리지 않고 즉시 승인합니다.
+ 가능한 가장 짧은 쓰기 지연 시간입니다.
+ WAL 쓰기가 완료되기 전에 시스템이 충돌하면 데이터가 손실될 위험이 있습니다.
+ 절대 내구성보다 속도가 우선하는 처리량이 많은 시나리오에 적합합니다.
### 부분 쓰기 처리
`accept_partial` 파라미터는 쓰기 배치에 오류가 있을 때 동작을 제어합니다.
`accept_partial`이 `true`인 경우(기본값)
+ 유효한 줄이 성공적으로 작성되었습니다.
+ 잘못된 줄이 거부됩니다.
+ 실패한 줄에 대한 세부 정보와 함께 400 상태를 반환합니다.
+ 일부 장애가 허용되는 대규모 배치 작업에 유용합니다.
`accept_partial`이 `false`인 경우
+ 어느 한 줄이라도 실패하면 전체 배치가 폐기됩니다.
+ 데이터가 작성되지 않습니다.
+ 오류 세부 정보와 함께 400 상태를 반환합니다.
+ 전부 아니면 전무 쓰기 시맨틱을 보장합니다.
### 호환성 API
호환성 API를 사용하면 기존 InfluxDB v1 또는 v2 워크로드를 InfluxDB 3로 원활하게 마이그레이션할 수 있습니다. 이러한 엔드포인트는 기존 InfluxDB 클라이언트 라이브러리, Telegraf 및 타사 통합과 연동됩니다.
**중요한 차이점:**
+ 테이블(측정값)의 태그는 일단 생성되면 변경할 수 없습니다.
+ 태그와 필드는 테이블 내에서 동일한 이름을 가질 수 없습니다.
+ 스키마 검증은 쓰기 시 적용됩니다.
#### InfluxDB v2 호환성
`/api/v2/write` 엔드포인트는 v2 클라이언트에 이전 버전과의 호환성을 제공합니다.
```
curl -i "https://your-cluster-endpoint:8086/api/v2/write?bucket=DATABASE_NAME&precision=s" \
--header "Authorization: Bearer DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
V2 API 파라미터:
| **파라미터** | **위치** | **설명** |
| --- | --- | --- |
| bucket \* | 쿼리 문자열 | 데이터베이스 이름에 매핑 |
| precision | 쿼리 문자열 | 타임스탬프 정밀도(ns, us, ms, s, m, h) |
| Authorization | 헤더 | 전달자 또는 토큰 체계 |
| Content-Encoding | 헤더 | gzip 또는 ID |
##### InfluxDB v1 호환성
`/write` 엔드포인트는 v1 클라이언트에 이전 버전과의 호환성을 제공합니다.
```
curl -i "https://your-cluster-endpoint:8086/write?db=DATABASE_NAME&precision=s" \
--user "any:DATABASE_TOKEN" \
--header "Content-type: text/plain; charset=utf-8" \
--data-binary 'home,room=kitchen temp=72 1641024000'
```
V1 인증 옵션:
+ 기본 인증: 토큰을 암호로 사용(`--user "any:TOKEN"`)
+ 쿼리 파라미터: URL의 `p=TOKEN`
+ 전달자/토큰 헤더: 표준 권한 부여 헤더
V1 API 파라미터:
| **파라미터** | **위치** | **설명** |
| --- | --- | --- |
| db \* | 쿼리 문자열 | 데이터베이스 이름 |
| precision | 쿼리 문자열 | 타임스탬프 정밀도 |
| p | 쿼리 문자열 | 쿼리 인증을 위한 토큰 |
| u | 쿼리 문자열 | 사용자 이름(무시됨) |
| Authorization | 헤더 | 여러 체계 지원됨 |
| Content-Encoding | 헤더 | gzip 또는 ID |
## 클라이언트 라이브러리 및 통합
### 공식 InfluxDB 3 클라이언트 라이브러리
InfluxDB 3 클라이언트 라이브러리는 시계열 데이터를 구성하고 쓰기 위한 기본 언어 인터페이스를 제공합니다.
+ **Python**: `influxdb3-python`
+ **Go**: `influxdb3-go`
+ **JavaScript/Node.js**: `influxdb3-js`
+ **Java**: `influxdb3-java`
+ **C\#**: `InfluxDB3.Client`
예제: Python 클라이언트
```
from influxdb3 import InfluxDBClient3
client = InfluxDBClient3(
host="your-cluster-endpoint:8086",
token="YOUR_TOKEN",
database="DATABASE_NAME"
)
# Write using line protocol
client.write("home,room=Living\\ Room temp=21.1,hum=35.9,co=0i")
# Write using Point objects
from influxdb3 import Point
point = Point("home") \
.tag("room", "Living Room") \
.field("temp", 21.1) \
.field("hum", 35.9) \
.field("co", 0)
client.write(point)
```
예제: Go 클라이언트
```
import "github.com/InfluxCommunity/influxdb3-go/v2/influxdb3"
client, err := influxdb3.New(influxdb3.ClientConfig{
Host: "your-cluster-endpoint:8086",
Token: "YOUR_TOKEN",
Database: "DATABASE_NAME",
})
point := influxdb3.NewPoint("home",
map[string]string{"room": "Living Room"},
map[string]any{
"temp": 24.5,
"hum": 40.5,
"co": 15,
},
time.Now(),
)
err = client.WritePoints(context.Background(), []*influxdb3.Point{point})
```
### 레거시 클라이언트 라이브러리
기존 v1 및 v2 워크로드의 경우 호환성 엔드포인트와 함께 레거시 클라이언트 라이브러리를 계속 사용할 수 있습니다.
예제: Node.js v1 클라이언트:
```
const Influx = require('influx')
const client = new Influx.InfluxDB({
host: 'your-cluster-endpoint',
port: 8086,
protocol: 'https',
database: 'DATABASE_NAME',
username: 'ignored',
password: 'DATABASE_TOKEN'
})
```
## 데이터 쓰기 모범 사례
데이터를 작성할 때 다음을 권장합니다.
+ 배치 최적화
+ 최적의 배치 크기: 요청당 5,000\~10,000줄 또는 10MB
+ 대량 페이로드에는 압축(gzip)을 사용합니다.
+ 더 나은 성능을 위해 어휘 순서로 키를 기준으로 태그를 정렬합니다.
+ 타임스탬프 정밀도
+ 필요에 맞는 가장 낮은 정밀도를 사용합니다.
+ 모호함을 피하기 위해 명시적으로 정밀도를 지정합니다.
+ 애플리케이션 전체에서 일관된 정밀도를 유지합니다.
+ 오류 처리
+ 일시적인 장애에 대한 재시도 로직을 구현합니다.
+ 복원력이 뛰어난 배치 작업을 위해 accept\_partial=true를 사용합니다.
+ CloudWatch 지표를 통해 쓰기 오류를 모니터링합니다.
+ 성능 튜닝
+ 처리량이 많은 시나리오에는 no\_sync=true를 사용합니다.
+ 여러 연결에 쓰기를 분산합니다.
+ 모든 쓰기 작업에 라이터/리더 엔드포인트를 사용합니다.
+ 스키마 고려 사항
+ 태그는 일단 생성되면 변경할 수 없습니다.
+ 필드와 태그는 동일한 이름을 공유할 수 없습니다.
+ 쿼리 패턴을 염두에 두고 스키마를 설계합니다.
+ 태그 카디널리티를 계속 제어합니다.
이전 버전과의 중요한 차이점:
+ 변경할 수 없는 태그: 테이블에 태그가 생성되면 태그 유형을 변경할 수 없습니다.
+ 태그 없음/필드 이름 충돌: 태그와 필드는 테이블 내에서 동일한 이름을 가질 수 없습니다.
+ 스키마 온 라이트: InfluxDB 3는 쓰기 시 데이터 유형을 검증합니다.
+ 자동 테이블 생성: 처음 쓸 때 테이블이 자동으로 생성됩니다.
+ 엄격한 유형 검사: 필드 유형은 모든 쓰기에서 일관되게 유지되어야 합니다.
적절한 쓰기 API를 활용하고 이러한 모범 사례를 따르면 고성능 및 데이터 무결성을 유지하면서 Timestream for InfluxDB 3 인스턴스에 시계열 데이터를 효율적으로 수집할 수 있습니다.