Ticker 문서

퀵스타트 — 5분

Ticker는 Maven Central에 올라간 두 개의 Spring Boot 스타터입니다 (io.stevelabs, Apache-2.0). 컬렉터 하나 + 감시할 앱마다 클라이언트 하나.

1. 컬렉터 띄우기

빈 Spring Boot 앱(또는 기존 운영용 앱)에 서버 스타터를 추가하고 켜면 끝. 시작한 뒤 http://localhost:8080 을 열면 상태 벽과 내장 UI가 그 앱에서 바로 서빙됩니다.

// build.gradle.kts
dependencies {
    implementation("io.stevelabs:ticker-server-spring-boot-starter:0.2.1")
}

<!-- pom.xml -->
<dependency>
    <groupId>io.stevelabs</groupId>
    <artifactId>ticker-server-spring-boot-starter</artifactId>
    <version>0.2.1</version>
</dependency>

# application.yml
ticker:
  server:
    enabled: true
  targets:                       # optional: things that can't self-register
    - { name: edge-nginx, type: HTTP, url: http://edge-nginx/healthz }

2. 서비스가 스스로 등록하게 하기

감시할 각 Spring Boot 앱에 클라이언트 스타터를 추가하세요 — 필요한 건 컬렉터 URL 하나뿐입니다. 감시 대상 앱의 Boot 버전에 맞는 스타터를 고르세요 (Boot 4.x → ticker-client-spring-boot-starter, Boot 3.2+ → ticker-client-spring-boot3-starter). 컬렉터 자체는 항상 Boot 4 / Java 21로 돌지만, Boot 3 앱도 HTTP로 문제없이 등록합니다.

dependencies {
    // on a Spring Boot 4.x app:
    implementation("io.stevelabs:ticker-client-spring-boot-starter:0.2.1")

    // …or on a Spring Boot 3.2+ app instead (same config, same behaviour):
    // implementation("io.stevelabs:ticker-client-spring-boot3-starter:0.2.1")
}

# application.yml — that's the whole client config
spring.application.name: orders-api
ticker.client.collector-url: http://ticker-collector:8080

클라이언트를 못 넣는 대상(nginx, 외부 API)은? 벽에서 클릭으로 HTTP 모니터를 추가하거나, targets 설정에 적으면 됩니다.

3. (선택) 코드로 설정

타깃과 알림 규칙은 TickerConfigurer 빈으로도 정의할 수 있습니다 — 설정을 코드리뷰에 태우고 싶을 때.

@Bean
fun tickerConfig() = TickerConfigurer { t ->
    t.addTarget("payments-api", ServiceType.HTTP, "https://payments/health", tags = listOf("prod"))
    t.configureAlert("cpu-process", threshold = 0.70, forSeconds = 15)
}

동작 방식

• 01클라이언트 스타터가 앱 시작 시 컬렉터에 POST로 자기를 등록하고, 30초마다 하트비트로 재등록합니다 — 그래서 컬렉터를 재배포해도 벽이 저절로 복원돼요. DB가 필요 없는 이유입니다.
• 02컬렉터는 가상 스레드로 모든 타깃을 병렬 폴링합니다. SPRING 타깃은 /actuator/health + 화이트리스트에 있는 지표만 읽고(env, configprops, heapdump는 절대 안 읽음), HTTP 타깃은 GET 한 번에 2xx면 정상.
• 03한 번 실패했다고 DOWN이 되지 않습니다 — N회 연속 실패(기본 3)여야 하고, 알림엔 쿨다운이 있어요. 순단 한 번으로 새벽에 페이지되는 일은 없습니다.
• 04현재 상태와 최근 히스토리는 전부 메모리에 있습니다. 그래프의 5분~7일 범위가 필요할 때만 히스토리를 옵트인으로 켜세요 (H2 파일 기본, MySQL/PostgreSQL 선택).

설정 레퍼런스

모든 프로퍼티는 표준 Spring @ConfigurationProperties입니다 — application.yml, 환경변수(relaxed binding: ticker.server.public-url ↔ TICKER_SERVER_PUBLIC_URL), 또는 TickerConfigurer 빈으로 설정하세요. IDE 자동완성과 인라인 문서가 전부 번들되어 있습니다.

설정 없이 띄우면: 벽 + 드릴다운, 인메모리, 알림 없음, DB 없음. 아래 표의 기본값이 곧 그 상태입니다.

ticker.server.* — 컬렉터 자신

ticker.poll.* — 헬스 폴링

ticker.targets — 정적 타깃

ticker.alert.* — 알림 (전부 기본 꺼짐)

ticker.history.* — 옵트인 지표 히스토리

ticker.client.* — 감시 대상 앱

붙여넣기용 — 프로덕션스러운 컬렉터 설정 한 벌:

# a fuller collector config, everything optional
ticker:
  server:
    base-path: /ticker                        # UI → /ticker/, API → /ticker/api/**
    public-url: https://ops.acme.com/ticker
    registration-expiry: 10m                  # autoscaling ghost cleanup
  poll:
    interval: 10s
    failure-threshold: 3
  alert:
    enabled: true
    slack-webhook-url: ${SLACK_WEBHOOK_URL:}
  history:
    enabled: true
    db: H2
    h2-path: /var/lib/ticker/history
    retention: 7d
    archive:
      enabled: true
      dir: /var/lib/ticker/history-archive

Slack 알림

알림은 두 갈래입니다. 장애형 — 서비스가 죽거나(🔴) 되살아날 때(🟢). 지표 임계형 — CPU>80% 같은 규칙이 지속 시간을 채우면(⚠️). 인스턴스 단위로 식별되어 hostname:port와 IP가 함께 옵니다.

웹훅 연결 — 3단계

1. 1api.slack.com/apps 에서 앱 하나 만들기 (From scratch, 워크스페이스 선택)
2. 2Incoming Webhooks 켜고 → Add New Webhook to Workspace → 채널 선택. 웹훅 URL 하나가 채널 하나에 바인딩됩니다 — 채널을 바꾸려면 웹훅을 새로 만드세요.
3. 3받은 URL을 환경변수로 넘기기 — yaml에 값을 적지 말고 ${SLACK_WEBHOOK_URL:} 패턴으로. 빈 값은 미설정으로 취급되어 알림이 로그로만 남습니다.

# application.yml
ticker:
  server:
    public-url: https://ops.acme.com/ticker   # "Open Ticker board" link in alerts
  alert:
    enabled: true
    slack-webhook-url: ${SLACK_WEBHOOK_URL:}  # env-templated; blank = alerts stay log-inert
    cooldown: 15m

배포는 장애가 아니다

롤링/블루그린 배포 때마다 🔴가 오면 아무도 알림을 안 믿게 됩니다. 그래서 두 가지가 기본으로 준비돼 있어요. 첫째, 정상 종료하는 인스턴스는 스스로 등록을 해제합니다 (deregister-on-shutdown, 기본 on) — 내려가는 파드는 조용히 벽에서 사라져요. 크래시는 셧다운 훅을 안 타니 그대로 DOWN으로 남고요 — 그게 맞으니까. 둘째, 더 큰 작업엔 silence 창을 거세요:

# before a deploy / maintenance — suppress alerts for 10 minutes
curl -X POST http://ticker:8080/api/alerts/silence \
  -H 'Content-Type: application/json' -d '{"minutes": 10}'

# check / lift it early
curl http://ticker:8080/api/alerts/silence
curl -X DELETE http://ticker:8080/api/alerts/silence

silence가 활성인 동안 발송은 억제되지만, 창이 끝날 때 아직 DOWN인 건 그때 알립니다. silence가 진짜 장애를 삼키는 일은 구조적으로 없습니다.

런타임 API

레플리카 & 인스턴스 구분

실무 배포에서 인스턴스에 이름을 하나씩 붙이는 사람은 없습니다 — ASG, Beanstalk, k8s 모두 같은 설정으로 N대가 한꺼번에 뜨죠. Ticker는 이걸 전제로 설계됐습니다. 레플리카들은 같은 이름(spring.application.name)을 공유하고, 각 인스턴스는 등록 시점에 자기 hostname:port + IP로 스스로를 구분합니다. 설정 파일 하나를 N대가 그대로 공유해도 서로 덮어쓰지 않아요.

벽에서는 같은 이름이 타일 하나로 묶입니다 — 8/8 UP 같은 집계, 인스턴스별 점 스트립, 그리고 아픈 인스턴스가 항상 위로 올라오는 워스트-퍼스트 행. 타일을 열면 상세 헤더에 HOST / IP / URL 아이덴티티 라인과 인스턴스 스위처(6대 이하면 칩, 그 이상은 드롭다운)가 있어서 한 대씩 파고들 수 있습니다.

운영 노트