InfluxDB

이 페이지는 Notion(AIOT-Team3-InsightON)에서 정리해 옮긴 내용입니다. 최신 원본은 Notion에서 확인하세요. (일회성 정리 — 자동 동기화 아님)

InfluxDB

시계열 데이터베이스(TSDB).

필수 용어 정리 (vs RDBMS)

RDBMS (MySQL 등)	InfluxDB	설명 및 특징
Database	Bucket	데이터가 저장되는 가장 큰 단위 (v1의 Database와 동일)
Table	Measurement	데이터의 종류 (예: cpu_usage, sensor_data)
Column (Indexed)	Tag	검색·필터링·그룹화 기준 메타데이터. 인덱스가 생성되며 오직 문자열만 가능 (예: host_id, region)
Column (일반)	Field	실제 측정값. 인덱스 없음, 숫자/문자/boolean 등 다양한 타입 가능 (예: temperature, cpu_percent)
Primary Key	Timestamp	데이터가 발생한 시간. InfluxDB의 핵심이자 필수 값

아키텍처 및 데이터 처리 특성

JPA를 다루던 백엔드 개발자가 가장 주의해야 할 InfluxDB의 내부 동작 방식.

트랜잭션과 정합성 (JPA와의 차이)

• No 트랜잭션: Rollback, Commit, Lock 개념이 아예 없음. 초당 수십만 건의 쓰기 성능을 위해 정합성을 포기한 구조 — 결제/주문 데이터가 아닌 모니터링 로그·센서 데이터 저장에만 써야 함.
• Overwrite: 동일한 Timestamp + 동일한 Measurement + 동일한 Tag 조합의 데이터가 들어오면 에러 대신 기존 데이터를 덮어씀.

내부 저장 엔진 (TSM & WAL)

• WAL(Write-Ahead Log): 서버 다운 시 데이터 유실을 막기 위해 들어오는 데이터를 디스크 로그 파일에 먼저 순차 기록
• Cache: 동시에 메모리에 올려 즉시 조회 가능하게 함
• TSM(Time Structured Merge-tree): 메모리가 차면 데이터를 시간 순 정렬·압축해 .tsm 디스크 파일로 저장

Spring Boot 코드 구현 가이드

의존성 추가

<!-- Source: https://mvnrepository.com/artifact/com.influxdb/influxdb-client-java -->
<dependency>
    <groupId>com.influxdb</groupId>
    <artifactId>influxdb-client-java</artifactId>
    <version>8.0.0</version>
    <scope>compile</scope>
</dependency>

환경 변수 설정 (예시 — 실제 값은 환경변수/시크릿으로 관리)

influxdb:
  url: http://localhost:8086
  token: "<INFLUXDB_TOKEN>"
  org: "my-org"
  bucket: "sensor_data_bucket"

InfluxDB Client Bean

import com.influxdb.client.InfluxDBClient;
import com.influxdb.client.InfluxDBClientFactory;
import com.influxdb.client.WriteOptions;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class InfluxDbConfig {

    @Value("${influxdb.url}")
    private String url;

    @Value("${influxdb.token}")
    private String token;

    @Value("${influxdb.org}")
    private String org;

    @Value("${influxdb.bucket}")
    private String bucket;

    @Bean
    public InfluxDBClient influxDBClient() {
        // 자동 배치 옵션 설정 (이 설정이 없으면 한 건씩 전송되어 서버에 부하가 갑니다)
        WriteOptions writeOptions = WriteOptions.builder()
                .batchSize(5000)          // 5,000건이 모이면 한 번에 전송
                .flushInterval(1000)      // 5,000건이 안 모여도 1초(1000ms)마다 전송
                .bufferLimit(100000)      // 메모리 버퍼 최대 크기 (Backpressure 대비)
                .build();

        return InfluxDBClientFactory.create(url, token.toCharArray(), org, bucket, writeOptions);
    }
}

데이터 삽입 서비스 로직 예시

JPA의 @Entity 대신 InfluxDB의 Point 객체를 만들어 WriteApi를 통해 비동기로 밀어넣습니다.

import com.influxdb.client.InfluxDBClient;
import com.influxdb.client.WriteApi;
import com.influxdb.client.domain.WritePrecision;
import com.influxdb.client.write.Point;
import org.springframework.stereotype.Service;

import javax.annotation.PreDestroy;
import java.time.Instant;

@Service
public class SensorDataService {

    private final InfluxDBClient influxDBClient;
    private final WriteApi writeApi;

    public SensorDataService(InfluxDBClient influxDBClient) {
        this.influxDBClient = influxDBClient;
        // makeWriteApi()는 데이터를 비동기/배치 방식으로 처리하는 API를 반환합니다.
        this.writeApi = influxDBClient.makeWriteApi();
    }

    public void saveSensorData(String serverId, String region, double cpuUsage) {
        // 1. Measurement 이름 지정 (Table 역할)
        Point point = Point.measurement("cpu_metrics")
                // 2. Tag 추가 (인덱스 O, 문자열만)
                .addTag("server_id", serverId)
                .addTag("region", region)
                // 3. Field 추가 (인덱스 X, 실제 값)
                .addField("usage_percent", cpuUsage)
                // 4. Timestamp 명시 (밀리초 단위)
                .time(Instant.now(), WritePrecision.MS);

        // API로 전송 (내부적으로 모아두었다가 설정한 Batch 사이즈/시간에 도달하면 InfluxDB로 쏨)
        writeApi.writePoint(point);
    }

    // 서버가 종료될 때 버퍼에 남아있는 데이터를 강제로 비워주기 위한 안전장치
    @PreDestroy
    public void close() {
        writeApi.close();
        influxDBClient.close();
    }
}

Notion 원본에는 token 값에 "my-super-secret-auth-token"이라는 예시 문자열이 있었는데, 실제 사용 중인 값처럼 보여 여기서는 플레이스홀더로 바꿨습니다. 실제 토큰은 InfluxDB 설정에서 발급받아 환경변수로만 관리하세요.