InfluxDB란?

InfluxDB는 시계열(Time Series) 데이터에 특화된 오픈소스 데이터베이스입니다.
시간 순서로 기록되는 대량의 데이터를 빠르게 쓰고, 시간 범위 기반으로 효율적으로 조회할 수 있도록 설계되었습니다.

시계열 데이터란?

시계열 데이터는 시간에 따라 연속적으로 기록되는 데이터입니다.

왜 InfluxDB를 사용하는가?

RDBMS로 시계열 데이터를 처리할 때의 문제

InfluxDB가 해결하는 것

InfluxDB 장단점

장점

단점

언제 InfluxDB를 사용해야 하는가?

적합한 경우 ✅

부적합한 경우 ❌

InfluxDB 버전 비교

이 강좌에서는 InfluxDB 2.x를 기준으로 설명합니다.

설치

Docker (권장)

docker run -d \
  --name influxdb \
  -p 8086:8086 \
  -v influxdb-data:/var/lib/influxdb2 \
  -e DOCKER_INFLUXDB_INIT_MODE=setup \
  -e DOCKER_INFLUXDB_INIT_USERNAME=admin \
  -e DOCKER_INFLUXDB_INIT_PASSWORD=InfluxPass123! \
  -e DOCKER_INFLUXDB_INIT_ORG=myorg \
  -e DOCKER_INFLUXDB_INIT_BUCKET=mybucket \
  -e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=my-super-secret-token \
  influxdb:2

# 웹 UI 접속
# http://localhost:8086

Linux (Ubuntu)

wget https://dl.influxdata.com/influxdb/releases/influxdb2_2.7.x_amd64.deb
sudo dpkg -i influxdb2_2.7.x_amd64.deb
sudo systemctl start influxdb
sudo systemctl enable influxdb

# 초기 설정
influx setup

Mac

brew install influxdb
brew services start influxdb

# 초기 설정
influx setup

Windows

1. InfluxDB 다운로드 페이지에서 Windows 바이너리 다운로드
2. 압축 해제 후 influxd.exe 실행
3. 브라우저에서 http://localhost:8086 접속하여 초기 설정

설치 확인

influx version
influx ping
# 웹 UI: http://localhost:8086

접속 방법

influx CLI

# 토큰 인증
influx config create \
  --config-name default \
  --host-url http://localhost:8086 \
  --org myorg \
  --token my-super-secret-token \
  --active

# 버킷 목록
influx bucket list

# 쿼리 실행
influx query 'from(bucket:"mybucket") |> range(start: -1h)'

HTTP API

# 데이터 쓰기
curl -X POST "http://localhost:8086/api/v2/write?org=myorg&bucket=mybucket" \
  -H "Authorization: Token my-super-secret-token" \
  -H "Content-Type: text/plain" \
  --data-raw "cpu,host=server01 usage=45.2 1714900000000000000"

# 데이터 조회
curl -X POST "http://localhost:8086/api/v2/query?org=myorg" \
  -H "Authorization: Token my-super-secret-token" \
  -H "Content-Type: application/vnd.flux" \
  --data 'from(bucket:"mybucket") |> range(start: -1h)'

TICK 스택 (InfluxDB 에코시스템)

InfluxDB 2.x에서는 Chronograf와 Kapacitor 기능이 내장되어 별도 설치가 불필요합니다.
시각화는 Grafana와 연동하는 것이 더 일반적입니다.

관련된 글 (influxdb > lecture-influxdb)

• [InfluxDB] 06. 운영 관리와 Troubleshooting
• [InfluxDB] 05. Task, 다운샘플링, 알림
• [InfluxDB] 04. Telegraf (데이터 수집 에이전트)
• [InfluxDB] 03. Flux 쿼리 언어
• [InfluxDB] 02. 데이터 모델 (Measurement, Tag, Field)
• [InfluxDB] 01. InfluxDB 소개 및 설치

데이터 모델 개요

InfluxDB의 데이터 모델은 RDBMS와 완전히 다릅니다.
시계열 데이터에 최적화된 구조로, 모든 데이터 포인트는 반드시 타임스탬프를 가집니다.

RDBMS ↔ InfluxDB 용어 매핑

Line Protocol (데이터 쓰기 형식)

InfluxDB에 데이터를 쓸 때 사용하는 텍스트 형식입니다.

<measurement>,<tag_key>=<tag_value>,... <field_key>=<field_value>,... <timestamp>

예시

cpu,host=server01,region=kr-central usage_user=45.2,usage_system=12.1 1714900000000000000
cpu,host=server02,region=kr-central usage_user=32.8,usage_system=8.5 1714900000000000000
temperature,sensor=s1,location=factory1 value=23.5 1714900000000000000

구성 요소 상세

Tag vs Field (핵심 구분)

이 구분을 잘못하면 성능에 큰 영향을 미칩니다.

Tag로 적합한 것 ✅

• 호스트명 (host=server01)
• 리전 (region=kr-central)
• 센서 ID (sensor=s1)
• 환경 (env=production)
• 서비스명 (service=api-gateway)

Field로 적합한 것 ✅

• CPU 사용률 (usage=45.2)
• 온도 (temperature=23.5)
• 응답 시간 (response_time=120)
• 요청 수 (count=1500)
• 에러 수 (errors=3)

Tag로 부적합한 것 ❌ (높은 카디널리티)

• 사용자 ID (수백만 종류)
• 요청 URL (무한 종류)
• 타임스탬프 문자열
• UUID

카디널리티(고유 값 수)가 높은 데이터를 Tag로 설정하면 인덱스가 비대해져 메모리 부족과 성능 저하가 발생합니다.

Series (시리즈)

Series는 동일한 Measurement + Tag 조합을 가진 데이터 포인트의 집합입니다.
InfluxDB 성능의 핵심 지표는 시리즈 카디널리티(총 시리즈 수)입니다.

# 아래는 3개의 서로 다른 시리즈
cpu,host=server01,region=kr    → Series 1
cpu,host=server02,region=kr    → Series 2
cpu,host=server01,region=us    → Series 3

시리즈 카디널리티 계산

시리즈 수 = Measurement 수 × Tag 조합 수

예: cpu measurement, host 100대, region 3개
시리즈 수 = 1 × 100 × 3 = 300 시리즈 (양호)

예: http_requests, user_id 100만명, endpoint 50개
시리즈 수 = 1 × 1,000,000 × 50 = 5천만 시리즈 (위험!)

Bucket (버킷)

InfluxDB 2.x에서 Bucket은 데이터 저장 공간 + 보존 정책을 합친 개념입니다.

# 버킷 생성 (30일 보존)
influx bucket create \
  --name monitoring \
  --org myorg \
  --retention 30d

# 버킷 목록
influx bucket list

# 버킷 삭제
influx bucket delete --name monitoring

보존 기간 (Retention)

# 보존 기간 변경
influx bucket update --name monitoring --retention 90d

데이터 쓰기

influx CLI

influx write \
  --bucket mybucket \
  --org myorg \
  --precision s \
  "cpu,host=server01 usage_user=45.2,usage_system=12.1 1714900000"

여러 포인트 한번에 쓰기

influx write --bucket mybucket --org myorg --precision ns << EOF
cpu,host=server01 usage_user=45.2,usage_system=12.1 1714900000000000000
cpu,host=server02 usage_user=32.8,usage_system=8.5 1714900000000000000
memory,host=server01 used_percent=72.5,available=8589934592 1714900000000000000
EOF

파일에서 쓰기

# data.lp (Line Protocol 파일)
influx write --bucket mybucket --org myorg --file data.lp

# CSV 파일
influx write --bucket mybucket --org myorg \
  --file data.csv \
  --header "#constant measurement,cpu" \
  --header "#datatype tag,double,double,dateTime:RFC3339"

데이터 모델 설계 예시

서버 모니터링

# Measurement: cpu
cpu,host=web01,region=kr,env=prod usage_user=45.2,usage_system=12.1,usage_idle=42.7

# Measurement: memory
memory,host=web01,region=kr,env=prod used_percent=72.5,available=8589934592

# Measurement: disk
disk,host=web01,path=/,device=sda1 used_percent=65.3,free=107374182400

IoT 센서

# Measurement: temperature
temperature,sensor_id=s001,location=factory1,floor=1F value=23.5,humidity=45.2

# Measurement: vibration
vibration,machine_id=m001,line=A frequency=120.5,amplitude=0.03

웹 애플리케이션 메트릭

# Measurement: http_requests
http_requests,method=GET,endpoint=/api/users,status=200 count=1,response_time=45

# Measurement: errors
errors,service=api,level=error count=1,message="timeout"

관련된 글 (influxdb > lecture-influxdb)

• [InfluxDB] 06. 운영 관리와 Troubleshooting
• [InfluxDB] 05. Task, 다운샘플링, 알림
• [InfluxDB] 04. Telegraf (데이터 수집 에이전트)
• [InfluxDB] 03. Flux 쿼리 언어
• [InfluxDB] 02. 데이터 모델 (Measurement, Tag, Field)
• [InfluxDB] 01. InfluxDB 소개 및 설치

Flux란?

Flux는 InfluxDB 2.x에서 사용하는 함수형 데이터 스크립팅 언어입니다.
파이프(|>) 연산자로 데이터를 단계별로 변환하는 파이프라인 방식입니다.

데이터 소스 |> 필터 |> 변환 |> 집계 |> 출력

기본 쿼리 구조

필수 3요소

from(bucket: "mybucket")        // 1. 데이터 소스
  |> range(start: -1h)          // 2. 시간 범위 (필수)
  |> filter(fn: (r) => r._measurement == "cpu")  // 3. 필터

시간 범위 (range)

// 상대 시간
|> range(start: -1h)              // 최근 1시간
|> range(start: -7d)              // 최근 7일
|> range(start: -30m, stop: -5m)  // 30분 전 ~ 5분 전

// 절대 시간
|> range(start: 2026-05-01T00:00:00Z, stop: 2026-05-05T23:59:59Z)

필터 (filter)

// 단일 조건
|> filter(fn: (r) => r._measurement == "cpu")

// 다중 조건 (AND)
|> filter(fn: (r) => r._measurement == "cpu" and r.host == "server01")

// OR 조건
|> filter(fn: (r) => r.host == "server01" or r.host == "server02")

// 필드 필터
|> filter(fn: (r) => r._field == "usage_user")

// 값 필터
|> filter(fn: (r) => r._value > 80.0)

// 정규식
|> filter(fn: (r) => r.host =~ /server0[1-3]/)

집계 함수

기본 집계

// 평균
from(bucket: "mybucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
  |> mean()

// 최대/최소
|> max()
|> min()

// 합계/개수
|> sum()
|> count()

// 마지막/첫 번째 값
|> last()
|> first()

// 중앙값/백분위
|> median()
|> quantile(q: 0.95)    // 95 퍼센타일

시간 윈도우 집계 (aggregateWindow)

// 5분 간격 평균
from(bucket: "mybucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
  |> aggregateWindow(every: 5m, fn: mean, createEmpty: false)

// 1시간 간격 최대값
|> aggregateWindow(every: 1h, fn: max)

// 1일 간격 합계
|> aggregateWindow(every: 1d, fn: sum)

그룹핑 (group)

// 호스트별 그룹핑 후 평균
from(bucket: "mybucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> group(columns: ["host"])
  |> mean()

// 그룹 해제
|> group()

변환 함수

정렬/제한

// 정렬
|> sort(columns: ["_time"], desc: true)
|> sort(columns: ["_value"], desc: true)

// 상위 N개
|> top(n: 10, columns: ["_value"])
|> bottom(n: 5, columns: ["_value"])

// 제한
|> limit(n: 100)
|> tail(n: 10)    // 마지막 10개

수학 연산

// 값 변환
|> map(fn: (r) => ({ r with _value: r._value * 100.0 }))

// 새 컬럼 추가
|> map(fn: (r) => ({ r with celsius: (r._value - 32.0) * 5.0 / 9.0 }))

// 절대값, 반올림
|> math.abs()
|> math.round(precision: 2)

시간 함수

// 시간 이동
|> timeShift(duration: -1d)

// 시간 단위 추출
|> map(fn: (r) => ({ r with hour: date.hour(t: r._time) }))

피벗 (Pivot)

// 필드를 컬럼으로 변환
from(bucket: "mybucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> pivot(rowKey: ["_time"], columnKey: ["_field"], valueColumn: "_value")
// 결과: _time | usage_user | usage_system | usage_idle

고급 함수

이동 평균 (Moving Average)

|> movingAverage(n: 5)          // 단순 이동 평균 (5포인트)
|> exponentialMovingAverage(n: 10)  // 지수 이동 평균
|> timedMovingAverage(every: 5m, period: 15m)  // 시간 기반

변화율 (Derivative)

// 초당 변화율
|> derivative(unit: 1s, nonNegative: true)

// 차이 (현재 - 이전)
|> difference(nonNegative: true)

// 증가분 (카운터용)
|> increase()

조건부 알림

// 임계값 초과 필터
from(bucket: "mybucket")
  |> range(start: -5m)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
  |> filter(fn: (r) => r._value > 90.0)

다운샘플링 (데이터 축소)

// 원본 데이터를 1시간 평균으로 축소하여 다른 버킷에 저장
from(bucket: "raw_data")
  |> range(start: -24h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> aggregateWindow(every: 1h, fn: mean)
  |> to(bucket: "downsampled_data", org: "myorg")

InfluxQL (SQL 유사 문법, 호환 모드)

InfluxDB 2.x에서도 InfluxQL을 사용할 수 있습니다 (1.x 호환).

-- 기본 조회
SELECT usage_user FROM cpu WHERE host = 'server01' AND time > now() - 1h

-- 집계
SELECT MEAN(usage_user) FROM cpu WHERE time > now() - 1h GROUP BY time(5m), host

-- 최근 값
SELECT LAST(usage_user) FROM cpu GROUP BY host

Flux vs InfluxQL 비교

관련된 글 (influxdb > lecture-influxdb)

• [InfluxDB] 06. 운영 관리와 Troubleshooting
• [InfluxDB] 05. Task, 다운샘플링, 알림
• [InfluxDB] 04. Telegraf (데이터 수집 에이전트)
• [InfluxDB] 03. Flux 쿼리 언어
• [InfluxDB] 02. 데이터 모델 (Measurement, Tag, Field)
• [InfluxDB] 01. InfluxDB 소개 및 설치

Telegraf란?

Telegraf는 InfluxData에서 개발한 플러그인 기반 메트릭 수집 에이전트입니다.
200개 이상의 입력/출력 플러그인을 지원하며, 시스템 메트릭, 애플리케이션 메트릭, 로그 등을 수집하여 InfluxDB에 전송합니다.

아키텍처

[Input Plugins] → [Processor Plugins] → [Aggregator Plugins] → [Output Plugins]
  (데이터 수집)      (데이터 변환)          (데이터 집계)          (데이터 전송)

설치

Linux

sudo apt install telegraf
# 또는
wget https://dl.influxdata.com/telegraf/releases/telegraf_1.x.x_amd64.deb
sudo dpkg -i telegraf_1.x.x_amd64.deb

Mac

brew install telegraf

Docker

docker run -d --name telegraf \
  -v /path/to/telegraf.conf:/etc/telegraf/telegraf.conf:ro \
  telegraf

설정 파일 (telegraf.conf)

기본 구조

# 글로벌 설정
[agent]
  interval = "10s"              # 수집 간격
  round_interval = true
  flush_interval = "10s"        # 전송 간격
  flush_jitter = "0s"

# 출력: InfluxDB 2.x
[[outputs.influxdb_v2]]
  urls = ["http://localhost:8086"]
  token = "my-super-secret-token"
  organization = "myorg"
  bucket = "mybucket"

# 입력: CPU
[[inputs.cpu]]
  percpu = true
  totalcpu = true
  collect_cpu_time = false

# 입력: 메모리
[[inputs.mem]]

# 입력: 디스크
[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs"]

# 입력: 네트워크
[[inputs.net]]

주요 Input 플러그인

시스템 메트릭

애플리케이션/서비스

기타

설정 예시

MySQL 모니터링

[[inputs.mysql]]
  servers = ["user:password@tcp(localhost:3306)/"]
  gather_table_schema = true
  gather_process_list = true
  gather_slave_status = true

Docker 모니터링

[[inputs.docker]]
  endpoint = "unix:///var/run/docker.sock"
  container_names = []
  timeout = "5s"
  perdevice = true
  total = true

HTTP 엔드포인트 체크

[[inputs.http_response]]
  urls = ["https://myapp.com/health", "https://api.myapp.com/status"]
  response_timeout = "5s"
  method = "GET"
  follow_redirects = true

커스텀 스크립트

[[inputs.exec]]
  commands = ["/opt/scripts/custom_metric.sh"]
  timeout = "5s"
  data_format = "influx"    # Line Protocol 형식 출력

실행 및 관리

# 설정 파일 테스트
telegraf --config telegraf.conf --test

# 포그라운드 실행
telegraf --config telegraf.conf

# 서비스 시작
sudo systemctl start telegraf
sudo systemctl enable telegraf

# 로그 확인
sudo journalctl -u telegraf -f

Telegraf + Grafana + InfluxDB 연동 구성

[서버/앱] → [Telegraf] → [InfluxDB] → [Grafana 대시보드]

이 구성은 서버 모니터링의 가장 일반적인 오픈소스 스택입니다.

관련된 글 (influxdb > lecture-influxdb)

• [InfluxDB] 06. 운영 관리와 Troubleshooting
• [InfluxDB] 05. Task, 다운샘플링, 알림
• [InfluxDB] 04. Telegraf (데이터 수집 에이전트)
• [InfluxDB] 03. Flux 쿼리 언어
• [InfluxDB] 02. 데이터 모델 (Measurement, Tag, Field)
• [InfluxDB] 01. InfluxDB 소개 및 설치

Task (예약 작업)

Task는 Flux 스크립트를 주기적으로 실행하는 예약 작업입니다.
다운샘플링, 데이터 변환, 알림 등에 활용됩니다.

Task 생성

웹 UI에서 생성

InfluxDB 웹 UI → Tasks → Create Task

Flux 스크립트로 생성

option task = {
    name: "downsample_cpu_hourly",
    every: 1h,
    offset: 5m    // 데이터 지연 고려 (5분 후 실행)
}

from(bucket: "raw_metrics")
  |> range(start: -task.every)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> aggregateWindow(every: 1h, fn: mean, createEmpty: false)
  |> to(bucket: "downsampled_metrics", org: "myorg")

Task 옵션

다운샘플링 (Downsampling)

원본 데이터를 요약하여 저장 공간을 절약하고 장기 조회 성능을 향상시킵니다.

전략 예시

다운샘플링 Task 예시

// 5분 평균으로 다운샘플링
option task = { name: "downsample_5m", every: 5m, offset: 30s }

from(bucket: "raw_metrics")
  |> range(start: -task.every)
  |> filter(fn: (r) => r._measurement == "cpu" or r._measurement == "memory")
  |> aggregateWindow(every: 5m, fn: mean, createEmpty: false)
  |> to(bucket: "metrics_5m", org: "myorg")

// 1시간 평균 + 최대값 다운샘플링
option task = { name: "downsample_1h", every: 1h, offset: 5m }

data = from(bucket: "metrics_5m")
  |> range(start: -task.every)
  |> filter(fn: (r) => r._measurement == "cpu")

// 평균
data |> aggregateWindow(every: 1h, fn: mean) |> to(bucket: "metrics_1h_avg")

// 최대값
data |> aggregateWindow(every: 1h, fn: max) |> to(bucket: "metrics_1h_max")

알림 (Alert / Check)

InfluxDB 2.x는 내장 알림 기능을 제공합니다.

구성 요소

Check 종류

Threshold Check 예시 (Flux)

import "influxdata/influxdb/monitor"

option task = { name: "cpu_alert", every: 1m }

data = from(bucket: "mybucket")
  |> range(start: -5m)
  |> filter(fn: (r) => r._measurement == "cpu" and r._field == "usage_user")
  |> aggregateWindow(every: 1m, fn: mean)

data
  |> monitor.check(
      crit: (r) => r._value > 90.0,
      warn: (r) => r._value > 70.0,
      info: (r) => r._value > 50.0,
      ok: (r) => r._value <= 50.0,
      messageFn: (r) => "CPU 사용률: ${string(v: r._value)}% on ${r.host}"
  )

Deadman Check (데이터 미수신 감지)

import "influxdata/influxdb/monitor"

option task = { name: "deadman_check", every: 5m }

from(bucket: "mybucket")
  |> range(start: -10m)
  |> filter(fn: (r) => r._measurement == "heartbeat")
  |> monitor.deadman(t: -5m)

Notification Endpoint 설정

Slack

influx notification-endpoint create \
  --name slack-alerts \
  --type slack \
  --url "https://hooks.slack.com/services/T00/B00/xxx"

Webhook (범용)

influx notification-endpoint create \
  --name webhook-alerts \
  --type http \
  --url "https://myapp.com/webhook/alerts" \
  --method POST

Task 관리

# Task 목록
influx task list

# Task 실행 이력
influx task log list --task-id <task-id>

# Task 비활성화/활성화
influx task update --id <task-id> --status inactive
influx task update --id <task-id> --status active

# Task 삭제
influx task delete --id <task-id>

# 수동 실행
influx task retry-failed --id <task-id>

관련된 글 (influxdb > lecture-influxdb)

• [InfluxDB] 06. 운영 관리와 Troubleshooting
• [InfluxDB] 05. Task, 다운샘플링, 알림
• [InfluxDB] 04. Telegraf (데이터 수집 에이전트)
• [InfluxDB] 03. Flux 쿼리 언어
• [InfluxDB] 02. 데이터 모델 (Measurement, Tag, Field)
• [InfluxDB] 01. InfluxDB 소개 및 설치

보안 및 인증

토큰 관리

# 토큰 목록
influx auth list

# 읽기 전용 토큰 생성
influx auth create \
  --org myorg \
  --read-bucket mybucket \
  --description "Grafana read-only"

# 읽기/쓰기 토큰 생성
influx auth create \
  --org myorg \
  --read-bucket mybucket \
  --write-bucket mybucket \
  --description "Telegraf write"

# 토큰 비활성화
influx auth inactive --id <token-id>

# 토큰 삭제
influx auth delete --id <token-id>

사용자 관리

# 사용자 생성
influx user create --name devuser --org myorg

# 비밀번호 설정
influx user password --name devuser

# 사용자 목록
influx user list

# 사용자 삭제
influx user delete --name devuser

백업과 복구

백업

# 전체 백업
influx backup /backup/influxdb/full_$(date +%Y%m%d)

# 특정 버킷만
influx backup /backup/influxdb/mybucket --bucket mybucket

# 압축 백업
influx backup /backup/influxdb/backup_$(date +%Y%m%d) --compression gzip

복구

# 전체 복구
influx restore /backup/influxdb/full_20260505

# 특정 버킷 복구
influx restore /backup/influxdb/mybucket --bucket mybucket

# 다른 이름으로 복구
influx restore /backup/influxdb/mybucket --bucket mybucket --new-bucket mybucket_restored

성능 튜닝

시리즈 카디널리티 관리

시리즈 카디널리티는 InfluxDB 성능의 가장 중요한 지표입니다.

# 시리즈 카디널리티 확인
influx query 'import "influxdata/influxdb"
influxdb.cardinality(bucket: "mybucket", start: -30d)'

// 측정별 시리즈 수 확인
import "influxdata/influxdb"

influxdb.cardinality(bucket: "mybucket", start: -30d)
  |> group(columns: ["_measurement"])
  |> count()

카디널리티 줄이기

스토리지 설정 (config.toml)

[storage]
  # TSM 엔진 캐시 크기
  cache-max-memory-size = "1g"
  
  # 캐시 스냅샷 크기
  cache-snapshot-memory-size = "25m"
  
  # 컴팩션 처리량
  compact-throughput = "48m"
  compact-throughput-burst = "48m"

쿼리 최적화

// ❌ 넓은 시간 범위 + 필터 없음
from(bucket: "mybucket")
  |> range(start: -30d)

// ✅ 좁은 시간 범위 + 구체적 필터
from(bucket: "mybucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu" and r.host == "server01")
  |> filter(fn: (r) => r._field == "usage_user")

// ❌ 불필요한 데이터 로드 후 제거
from(bucket: "mybucket")
  |> range(start: -1h)
  |> last()

// ✅ pushdown 최적화 (filter를 먼저)
from(bucket: "mybucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "cpu")
  |> last()

모니터링

내부 메트릭 확인

# /metrics 엔드포인트 (Prometheus 형식)
curl http://localhost:8086/metrics

# 주요 지표
# influxdb_organizations_total
# influxdb_buckets_total
# influxdb_series_total (시리즈 카디널리티)
# go_memstats_alloc_bytes (메모리 사용량)
# http_api_requests_total (API 요청 수)

디스크 사용량 확인

# 데이터 디렉토리 크기
du -sh /var/lib/influxdb2/engine/

# 버킷별 크기
du -sh /var/lib/influxdb2/engine/data/*

자주 발생하는 문제

1. 높은 시리즈 카디널리티로 인한 성능 저하

증상: 메모리 사용량 급증, 쿼리 느려짐, OOM

// 카디널리티 확인
import "influxdata/influxdb"
influxdb.cardinality(bucket: "mybucket", start: -7d)

2. 디스크 용량 부족

# 데이터 삭제 (시간 범위)
influx delete \
  --bucket mybucket \
  --start 2025-01-01T00:00:00Z \
  --stop 2025-06-01T00:00:00Z

# 특정 measurement 삭제
influx delete \
  --bucket mybucket \
  --start 1970-01-01T00:00:00Z \
  --stop $(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --predicate '_measurement="old_metric"'

3. 쓰기 실패 (Write Timeout)

4. 쿼리 타임아웃

# 쿼리 타임아웃 설정 (config.toml)
# query-timeout = "30s"

5. Telegraf 데이터 미수신

운영 체크리스트

DB 선택 가이드 (최종 비교)

관련된 글 (influxdb > lecture-influxdb)

• [InfluxDB] 06. 운영 관리와 Troubleshooting
• [InfluxDB] 05. Task, 다운샘플링, 알림
• [InfluxDB] 04. Telegraf (데이터 수집 에이전트)
• [InfluxDB] 03. Flux 쿼리 언어
• [InfluxDB] 02. 데이터 모델 (Measurement, Tag, Field)
• [InfluxDB] 01. InfluxDB 소개 및 설치

MongoDB란?

MongoDB는 문서(Document) 지향 NoSQL 데이터베이스입니다.
JSON과 유사한 BSON(Binary JSON) 형식으로 데이터를 저장하며, 유연한 스키마와 수평 확장을 제공합니다.

RDBMS vs MongoDB 비교

RDBMS ↔ MongoDB 용어 매핑

MongoDB 주요 특징

MongoDB 활용 사례

설치

Windows

1. MongoDB 다운로드 페이지에서 MSI 설치 파일 다운로드
2. mongodb-windows-x86_64-x.x.x-signed.msi 실행
3. “Complete” 설치 선택
4. “Install MongoDB as a Service” 체크
5. MongoDB Compass (GUI) 함께 설치 선택

Mac

# Homebrew
brew tap mongodb/brew
brew install mongodb-community@7.0
brew services start mongodb-community@7.0

Linux (Ubuntu)

# GPG 키 및 저장소 추가
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg --dearmor
echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

sudo apt update
sudo apt install mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod

Docker

docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=MongoPass123! \
  -v mongodata:/data/db \
  mongo:7

# 접속
docker exec -it mongodb mongosh -u admin -p MongoPass123!

설치 확인

mongosh
# 또는
mongosh "mongodb://localhost:27017"

db.version()

접속 방법

mongosh (MongoDB Shell)

# 로컬 접속
mongosh

# 인증 접속
mongosh -u admin -p MongoPass123! --authenticationDatabase admin

# 원격 접속
mongosh "mongodb://192.168.1.100:27017"

# Connection String (URI)
mongosh "mongodb://admin:MongoPass123!@localhost:27017/mydb?authSource=admin"

기본 셸 명령어

show dbs              // 데이터베이스 목록
use mydb              // 데이터베이스 전환 (없으면 자동 생성)
show collections      // 컬렉션 목록
db.stats()            // 현재 DB 통계
db.version()          // 버전 확인
exit                  // 종료

GUI 도구

문서(Document) 구조 예시

// RDBMS의 한 행(Row)에 해당하는 MongoDB 문서
{
    _id: ObjectId("507f1f77bcf86cd799439011"),  // 자동 생성 PK
    name: "홍길동",
    age: 30,
    email: "hong@test.com",
    address: {                    // 중첩 문서 (Embedded Document)
        city: "서울",
        zipcode: "06000"
    },
    hobbies: ["독서", "등산", "코딩"],  // 배열
    orders: [                     // 배열 + 중첩 문서
        { product: "노트북", price: 1500000, date: ISODate("2026-01-15") },
        { product: "마우스", price: 50000, date: ISODate("2026-03-20") }
    ],
    created_at: ISODate("2024-01-01T00:00:00Z"),
    is_active: true
}

관련된 글 (mongodb > lecture-mongodb)

• [MongoDB] 10. 자주 발생하는 Troubleshooting
• [MongoDB] 09. 성능 튜닝과 모니터링
• [MongoDB] 08. 백업과 복구
• [MongoDB] 07. 보안과 사용자 관리
• [MongoDB] 06. Replica Set과 Sharding (고가용성/확장)
• [MongoDB] 05. 스키마 설계 (Embedding vs Referencing)
• [MongoDB] 04. 인덱스 (Index)
• [MongoDB] 03. Aggregation Pipeline (집계)
• [MongoDB] 02. CRUD 기본 (문서 삽입, 조회, 수정, 삭제)
• [MongoDB] 01. MongoDB 소개 및 설치

데이터베이스와 컬렉션

데이터베이스 관리

// 데이터베이스 목록
show dbs

// 데이터베이스 전환 (없으면 첫 문서 삽입 시 자동 생성)
use mydb

// 현재 데이터베이스 확인
db

// 데이터베이스 삭제
db.dropDatabase()

컬렉션 관리

// 컬렉션 목록
show collections

// 컬렉션 생성 (명시적, 보통 자동 생성)
db.createCollection("users")

// 옵션과 함께 생성
db.createCollection("logs", {
    capped: true,       // 고정 크기 컬렉션
    size: 104857600,    // 100MB
    max: 100000         // 최대 문서 수
})

// 컬렉션 삭제
db.users.drop()

INSERT (문서 삽입)

단일 문서 삽입

db.users.insertOne({
    name: "홍길동",
    age: 30,
    email: "hong@test.com",
    dept: "개발팀",
    salary: 5000000,
    hire_date: new Date("2024-01-15"),
    skills: ["JavaScript", "Python", "MongoDB"],
    address: { city: "서울", district: "강남구" }
})
// { acknowledged: true, insertedId: ObjectId("...") }

다중 문서 삽입

db.users.insertMany([
    { name: "김철수", age: 25, dept: "기획팀", salary: 4500000 },
    { name: "이영희", age: 28, dept: "개발팀", salary: 5500000 },
    { name: "박민수", age: 35, dept: "디자인팀", salary: 4800000 },
    { name: "최지은", age: 32, dept: "개발팀", salary: 6000000 }
])

_id 직접 지정

db.users.insertOne({
    _id: "user_001",    // 직접 지정 가능 (중복 불가)
    name: "관리자",
    role: "admin"
})

FIND (문서 조회)

기본 조회

// 전체 조회
db.users.find()

// 보기 좋게 출력
db.users.find().pretty()

// 조건 조회
db.users.find({ dept: "개발팀" })

// 단일 문서 조회 (첫 번째 매칭)
db.users.findOne({ name: "홍길동" })

비교 연산자

db.users.find({ salary: { $gte: 5000000 } })
db.users.find({ age: { $gt: 25, $lt: 35 } })
db.users.find({ dept: { $in: ["개발팀", "기획팀"] } })
db.users.find({ dept: { $ne: "디자인팀" } })

논리 연산자

// AND (기본)
db.users.find({ dept: "개발팀", salary: { $gte: 5000000 } })

// $and (명시적)
db.users.find({ $and: [{ dept: "개발팀" }, { salary: { $gte: 5000000 } }] })

// $or
db.users.find({ $or: [{ dept: "개발팀" }, { dept: "기획팀" }] })

// $not
db.users.find({ age: { $not: { $gte: 30 } } })

// $nor (모두 아닌)
db.users.find({ $nor: [{ dept: "개발팀" }, { dept: "기획팀" }] })

필드/타입 연산자

// 필드 존재 여부
db.users.find({ email: { $exists: true } })
db.users.find({ phone: { $exists: false } })

// 타입 확인
db.users.find({ age: { $type: "number" } })

// 정규식
db.users.find({ name: { $regex: /^홍/ } })
db.users.find({ email: { $regex: /test\.com$/, $options: "i" } })

배열 쿼리

// 배열에 특정 값 포함
db.users.find({ skills: "Python" })

// 배열 크기
db.users.find({ skills: { $size: 3 } })

// $all: 모든 값 포함
db.users.find({ skills: { $all: ["JavaScript", "Python"] } })

// $elemMatch: 배열 요소 조건
db.users.find({ orders: { $elemMatch: { price: { $gt: 100000 } } } })

중첩 문서 쿼리

// 점 표기법 (Dot Notation)
db.users.find({ "address.city": "서울" })
db.users.find({ "orders.0.product": "노트북" })

프로젝션 (반환 필드 선택)

// 특정 필드만 반환 (1: 포함, 0: 제외)
db.users.find({}, { name: 1, email: 1, _id: 0 })

// 특정 필드 제외
db.users.find({}, { password: 0, __v: 0 })

정렬, 제한, 건너뛰기

// 정렬 (1: 오름차순, -1: 내림차순)
db.users.find().sort({ salary: -1 })
db.users.find().sort({ dept: 1, salary: -1 })

// 제한
db.users.find().limit(5)

// 건너뛰기 (페이징)
db.users.find().skip(10).limit(5)

// 개수
db.users.countDocuments({ dept: "개발팀" })
db.users.estimatedDocumentCount()   // 빠른 추정치

UPDATE (문서 수정)

수정 연산자

단일 문서 수정

// $set: 필드 값 변경
db.users.updateOne(
    { name: "홍길동" },
    { $set: { salary: 5500000, dept: "인사팀" } }
)

// $inc: 숫자 증감
db.users.updateOne(
    { name: "홍길동" },
    { $inc: { salary: 500000, age: 1 } }
)

// $unset: 필드 삭제
db.users.updateOne(
    { name: "홍길동" },
    { $unset: { phone: "" } }
)

// $push: 배열에 추가
db.users.updateOne(
    { name: "홍길동" },
    { $push: { skills: "Redis" } }
)

// $addToSet: 중복 없이 배열에 추가
db.users.updateOne(
    { name: "홍길동" },
    { $addToSet: { skills: "Python" } }  // 이미 있으면 무시
)

// $pull: 배열에서 제거
db.users.updateOne(
    { name: "홍길동" },
    { $pull: { skills: "Python" } }
)

다중 문서 수정

// 조건에 맞는 모든 문서 수정
db.users.updateMany(
    { dept: "개발팀" },
    { $inc: { salary: 500000 } }
)

Upsert (없으면 삽입, 있으면 수정)

db.users.updateOne(
    { email: "new@test.com" },
    { $set: { name: "신규유저", age: 20 } },
    { upsert: true }
)

replaceOne (문서 전체 교체)

db.users.replaceOne(
    { name: "홍길동" },
    { name: "홍길동", age: 31, dept: "CTO", salary: 8000000 }
)

DELETE (문서 삭제)

// 단일 문서 삭제
db.users.deleteOne({ name: "홍길동" })

// 다중 문서 삭제
db.users.deleteMany({ dept: "기획팀" })

// 전체 삭제
db.users.deleteMany({})

// 컬렉션 자체 삭제 (더 빠름)
db.users.drop()

findOneAndUpdate / findOneAndDelete

수정/삭제와 동시에 해당 문서를 반환합니다.

// 수정 후 새 문서 반환
db.users.findOneAndUpdate(
    { name: "홍길동" },
    { $inc: { salary: 100000 } },
    { returnDocument: "after" }   // "before" 또는 "after"
)

// 삭제하면서 삭제된 문서 반환
db.users.findOneAndDelete({ name: "홍길동" })

관련된 글 (mongodb > lecture-mongodb)

• [MongoDB] 10. 자주 발생하는 Troubleshooting
• [MongoDB] 09. 성능 튜닝과 모니터링
• [MongoDB] 08. 백업과 복구
• [MongoDB] 07. 보안과 사용자 관리
• [MongoDB] 06. Replica Set과 Sharding (고가용성/확장)
• [MongoDB] 05. 스키마 설계 (Embedding vs Referencing)
• [MongoDB] 04. 인덱스 (Index)
• [MongoDB] 03. Aggregation Pipeline (집계)
• [MongoDB] 02. CRUD 기본 (문서 삽입, 조회, 수정, 삭제)
• [MongoDB] 01. MongoDB 소개 및 설치

Aggregation Pipeline이란?

Aggregation Pipeline은 문서를 여러 단계(Stage)를 거쳐 변환하고 집계하는 프레임워크입니다.
RDBMS의 GROUP BY, HAVING, JOIN, 서브쿼리 등을 대체합니다.

컬렉션 → [Stage 1] → [Stage 2] → [Stage 3] → ... → 결과

주요 Stage

$match (필터링)

// WHERE dept = '개발팀' AND salary >= 5000000
db.users.aggregate([
    { $match: { dept: "개발팀", salary: { $gte: 5000000 } } }
])

$group (그룹핑)

// 부서별 인원수, 평균급여
db.users.aggregate([
    { $group: {
        _id: "$dept",                    // 그룹핑 기준
        count: { $sum: 1 },              // COUNT
        avg_salary: { $avg: "$salary" }, // AVG
        max_salary: { $max: "$salary" }, // MAX
        min_salary: { $min: "$salary" }, // MIN
        total_salary: { $sum: "$salary" } // SUM
    }}
])

집계 연산자

$project (필드 선택/변환)

db.users.aggregate([
    { $project: {
        _id: 0,
        name: 1,
        dept: 1,
        annual_salary: { $multiply: ["$salary", 12] },
        name_dept: { $concat: ["$name", " (", "$dept", ")"] }
    }}
])

$sort / $limit / $skip

// 급여 높은 순 상위 5명
db.users.aggregate([
    { $sort: { salary: -1 } },
    { $limit: 5 }
])

// 페이징 (2페이지, 페이지당 10건)
db.users.aggregate([
    { $sort: { _id: 1 } },
    { $skip: 10 },
    { $limit: 10 }
])

$unwind (배열 펼치기)

배열 필드를 개별 문서로 분리합니다.

// 원본: { name: "홍길동", skills: ["JS", "Python", "MongoDB"] }
// 결과: 3개 문서로 분리

db.users.aggregate([
    { $unwind: "$skills" },
    { $group: {
        _id: "$skills",
        count: { $sum: 1 }
    }},
    { $sort: { count: -1 } }
])
// 스킬별 보유 인원 수

$lookup (JOIN)

다른 컬렉션과 조인합니다.

// users 컬렉션의 dept_id로 departments 컬렉션 조인
db.users.aggregate([
    { $lookup: {
        from: "departments",        // 조인할 컬렉션
        localField: "dept_id",      // 현재 컬렉션 필드
        foreignField: "_id",        // 대상 컬렉션 필드
        as: "dept_info"             // 결과 배열 필드명
    }},
    { $unwind: "$dept_info" },      // 배열을 단일 문서로
    { $project: {
        name: 1,
        salary: 1,
        dept_name: "$dept_info.name"
    }}
])

Pipeline $lookup (복잡한 조인, MongoDB 3.6+)

db.orders.aggregate([
    { $lookup: {
        from: "products",
        let: { product_id: "$product_id" },
        pipeline: [
            { $match: { $expr: { $eq: ["$_id", "$$product_id"] } } },
            { $project: { name: 1, price: 1 } }
        ],
        as: "product"
    }}
])

$addFields / $set

// 기존 필드 유지하면서 새 필드 추가
db.users.aggregate([
    { $addFields: {
        annual_salary: { $multiply: ["$salary", 12] },
        is_senior: { $gte: ["$age", 30] }
    }}
])

$bucket (범위별 그룹핑)

// 급여 구간별 인원 수
db.users.aggregate([
    { $bucket: {
        groupBy: "$salary",
        boundaries: [0, 3000000, 5000000, 7000000, 10000000],
        default: "기타",
        output: {
            count: { $sum: 1 },
            names: { $push: "$name" }
        }
    }}
])

$facet (다중 파이프라인)

하나의 입력으로 여러 파이프라인을 동시에 실행합니다.

db.users.aggregate([
    { $facet: {
        "부서별통계": [
            { $group: { _id: "$dept", count: { $sum: 1 } } }
        ],
        "급여상위3": [
            { $sort: { salary: -1 } },
            { $limit: 3 },
            { $project: { name: 1, salary: 1 } }
        ],
        "전체통계": [
            { $group: { _id: null, total: { $sum: 1 }, avg_salary: { $avg: "$salary" } } }
        ]
    }}
])

실전 예시: SQL → Aggregation 변환

SQL

SELECT dept, COUNT(*) as count, AVG(salary) as avg_sal
FROM users
WHERE age >= 25
GROUP BY dept
HAVING COUNT(*) >= 2
ORDER BY avg_sal DESC;

MongoDB Aggregation

db.users.aggregate([
    { $match: { age: { $gte: 25 } } },
    { $group: {
        _id: "$dept",
        count: { $sum: 1 },
        avg_sal: { $avg: "$salary" }
    }},
    { $match: { count: { $gte: 2 } } },
    { $sort: { avg_sal: -1 } }
])

관련된 글 (mongodb > lecture-mongodb)

• [MongoDB] 10. 자주 발생하는 Troubleshooting
• [MongoDB] 09. 성능 튜닝과 모니터링
• [MongoDB] 08. 백업과 복구
• [MongoDB] 07. 보안과 사용자 관리
• [MongoDB] 06. Replica Set과 Sharding (고가용성/확장)
• [MongoDB] 05. 스키마 설계 (Embedding vs Referencing)
• [MongoDB] 04. 인덱스 (Index)
• [MongoDB] 03. Aggregation Pipeline (집계)
• [MongoDB] 02. CRUD 기본 (문서 삽입, 조회, 수정, 삭제)
• [MongoDB] 01. MongoDB 소개 및 설치

인덱스 종류

인덱스 생성 및 관리

생성

// 단일 필드 (1: 오름차순, -1: 내림차순)
db.users.createIndex({ email: 1 })

// 유니크 인덱스
db.users.createIndex({ email: 1 }, { unique: true })

// 복합 인덱스
db.users.createIndex({ dept: 1, salary: -1 })

// 배열 필드 (Multikey, 자동 감지)
db.users.createIndex({ skills: 1 })

// TTL 인덱스 (60초 후 자동 삭제)
db.sessions.createIndex({ created_at: 1 }, { expireAfterSeconds: 60 })

// 부분 인덱스 (조건 만족하는 문서만)
db.users.createIndex(
    { email: 1 },
    { partialFilterExpression: { is_active: true } }
)

// 텍스트 인덱스
db.articles.createIndex({ title: "text", content: "text" })

// 지리공간 인덱스
db.stores.createIndex({ location: "2dsphere" })

// 와일드카드 인덱스 (동적 필드)
db.products.createIndex({ "attributes.$**": 1 })

// 백그라운드 생성 (MongoDB 4.2+ 기본)
db.users.createIndex({ name: 1 }, { name: "idx_name" })

조회

// 인덱스 목록
db.users.getIndexes()

// 인덱스 크기
db.users.stats().indexSizes

// 인덱스 사용 통계
db.users.aggregate([{ $indexStats: {} }])

삭제

// 이름으로 삭제
db.users.dropIndex("idx_name")

// 정의로 삭제
db.users.dropIndex({ email: 1 })

// _id 제외 모든 인덱스 삭제
db.users.dropIndexes()

실행 계획 (explain)

// 실행 계획 확인
db.users.find({ dept: "개발팀" }).explain("executionStats")

주요 확인 항목

Stage 종류

복합 인덱스 설계 (ESR 규칙)

복합 인덱스의 필드 순서는 성능에 큰 영향을 미칩니다.

ESR 규칙 (Equality → Sort → Range)

// 쿼리: dept = "개발팀" AND age >= 25 ORDER BY salary DESC
// 최적 인덱스: { dept: 1, salary: -1, age: 1 }
db.users.createIndex({ dept: 1, salary: -1, age: 1 })

TTL 인덱스 (자동 만료)

지정된 시간이 지나면 문서를 자동으로 삭제합니다. 세션, 로그, 임시 데이터에 유용합니다.

// 30분 후 자동 삭제
db.sessions.createIndex({ created_at: 1 }, { expireAfterSeconds: 1800 })

// 특정 시점에 삭제 (expireAt 필드 값 기준)
db.events.createIndex({ expireAt: 1 }, { expireAfterSeconds: 0 })
db.events.insertOne({
    event: "promotion",
    expireAt: new Date("2026-12-31T23:59:59Z")  // 이 시점에 삭제
})

텍스트 인덱스와 검색

// 텍스트 인덱스 생성
db.articles.createIndex({ title: "text", content: "text" })

// 텍스트 검색
db.articles.find({ $text: { $search: "MongoDB 튜토리얼" } })

// 관련도 점수와 함께
db.articles.find(
    { $text: { $search: "MongoDB" } },
    { score: { $meta: "textScore" } }
).sort({ score: { $meta: "textScore" } })

// 구문 검색 (정확한 문구)
db.articles.find({ $text: { $search: '"MongoDB 설치"' } })

// 제외 검색
db.articles.find({ $text: { $search: "MongoDB -설치" } })

인덱스 설계 가이드라인

관련된 글 (mongodb > lecture-mongodb)

• [MongoDB] 10. 자주 발생하는 Troubleshooting
• [MongoDB] 09. 성능 튜닝과 모니터링
• [MongoDB] 08. 백업과 복구
• [MongoDB] 07. 보안과 사용자 관리
• [MongoDB] 06. Replica Set과 Sharding (고가용성/확장)
• [MongoDB] 05. 스키마 설계 (Embedding vs Referencing)
• [MongoDB] 04. 인덱스 (Index)
• [MongoDB] 03. Aggregation Pipeline (집계)
• [MongoDB] 02. CRUD 기본 (문서 삽입, 조회, 수정, 삭제)
• [MongoDB] 01. MongoDB 소개 및 설치