config.lua 한 줄부터 C 라이브러리까지

개요

view= / file= / Ctrl+O / Ctrl+F

이 네 가지만 알면 매뉴얼 전체를 읽을 준비가 끝납니다.

직접 눌러보고 싶다면 실제 라이브 인스턴스가 있습니다 — 홈페이지 "직접 체험하기" 섹션에서 SSH 없이 바로 확인할 수 있고, 다운로드 패키지를 받았다면 아래처럼 manual-1/· manual-2/가 그대로 들어있어 직접 실행해볼 수 있습니다.

manual-1 / manual-2 직접 실행하기

압축을 풀면 생기는 tapas-eye/ 디렉터리 루트에서 아래 명령을 그대로 실행하면 됩니다 — 두 매뉴얼 모두 --config만 바꿔서 같은 바이너리로 띄웁니다.

--web-port를 붙이면 브라우저에서 http://<서버주소>:8080으로 접속합니다. tty가 필요한 TUI 앱이라 tmux/screen 세션 안에서 실행해야 한다는 점 등 실행 환경 주의사항은 바로 아래 콜아웃 참고.

manual-2는 위 명령만으로 6단계 전부 바로 동작합니다. manual-1은 대부분 그대로 동작하지만, "SHM 구조체"·"전문별 처리 건수"·"다중 SHM 조인"· "SHM 값 편집" 네 항목만 예시 데이터로 SHM을 한 번 채워야 값이 보입니다(재부팅 전까지 유지 — 매번 반복할 필요 없음). 소스는 examples/에 있고 컴파일 후 실행하면 됩니다:

# SHM 구조체 / 전문별 처리 건수 / 다중 SHM 조인 / SHM 값 편집 — 각 1회만 실행해두면 됨
gcc -o /tmp/demo_koscom examples/demo_koscom.c && /tmp/demo_koscom
gcc -o /tmp/demo_msg_stats examples/demo_msg_stats.c && /tmp/demo_msg_stats
gcc -o /tmp/demo_msg_join examples/demo_msg_join.c && /tmp/demo_msg_join
gcc -o /tmp/demo_loglevel_ctrl examples/demo_loglevel_ctrl.c && /tmp/demo_loglevel_ctrl

# 메시지 큐 — POSIX MQ 두 개를 채움 (마찬가지로 1회만 실행)
gcc -o /tmp/demo_queue examples/demo_queue.c -lrt && /tmp/demo_queue

정리하고 싶으면 ipcrm -M 0x1234(SHM 구조체) · ipcrm -M 0x1300(전문별 처리 건수) · ipcrm -M 0x1301 ; ipcrm -M 0x1302 ; ipcrm -M 0x1303(다중 SHM 조인) · ipcrm -M 0x1350(SHM 값 편집) · rm -f /dev/mqueue/tapas_demo_orders /dev/mqueue/tapas_demo_alerts(메시지 큐)로 지울 수 있지만, 지우기 전까지는 화면에 그대로 남아있는 게 정상 동작이니 서두를 필요는 없습니다.

manual-1 · 1

config.lua만으로 되는 화면들

이 메뉴("기본기능")의 항목은 전부 view= 한 줄이면 됩니다 — Lua 파일이 단 하나도 없습니다. C 쪽에 이미 구현된 view 엔진(system/process/log/queue/ disk/net 6종 + SHM 구조체 파서 1종)을 config.lua의 menus → items 배열에 테이블 하나만 추가해서 "켜는" 방식이라, 재빌드는 물론 문법 오류만 없으면 재시작조차 필요 없습니다 — 게이트웨이 모드에서는 파일 저장 즉시(최대 1초) 새 인스턴스로 반영됩니다.

실행 화면 · view = "system" 한 줄의 결과

나머지 5개(프로세스/로그/큐/디스크/네트워크)도 문법은 똑같습니다 — 아래 표에서 view id와 화면별 옵션만 바꾸면 됩니다.

SHM 구조체 — 필드 160개짜리 C 구조체를 그대로 표로

나머지 두 항목은 SHM(공유메모리)에 C 구조체 배열을 그대로 써 둔 프로그램을 조회 프로그램 없이 바로 표로 보여주는, tapas-eye의 핵심 기능입니다. 예시로 쓴 KOSCOM_STOCK_A0은 실제 코스콤 시세 구조체 형태로, 필드가 160개가 넘습니다 — 기본(가로: 행=레코드, 열=필드) 표로 그리면 화면 폭을 한참 넘기기 때문에, 아래처럼 orientation = "vertical"로 행/열을 뒤집어서 필드가 아무리 많아도 가로로 안 넘치게 합니다.

SHM 구조체 (config)

필드 160개가 넘는 실제 시세 구조체(KOSCOM_STOCK_A0)를 헤더 파일 그대로 파싱합니다.

{
  label   = "SHM 구조체 (config)",
  view    = "manual_shmstruct_cfg",
  shm_key = 0x1234,
  header  = "examples/koscom_stock.h",
  struct  = "KOSCOM_STOCK_A0",
  start_index = 3,
  -- show 생략 = 전체 필드 표시. 필드가 160개+라 기본(가로: 행=레코드,
  -- 열=필드) 표로는 폭을 훨씬 넘긴다 — orientation="vertical"로
  -- 행=필드/열=레코드로 뒤집어서 필드가 아무리 많아도 안 넘치게 한다.
  orientation   = "vertical",
  vertical_rows = 3,  -- ←/→로 나란히 볼 레코드 수. PgUp/PgDn은 필드 스크롤
  filter = "",
}

실행 화면 · orientation="vertical"

전문별 처리 건수 — 헤더+데이터 SHM, 한글 라벨, 다단 배치

거래소 전문(메시지 타입)별 수신/처리/DB저장 건수 — 실무에서 가장 흔한 운영 모니터링 패턴입니다. 이 예시는 "헤더 구조체(등록된 전문 종류 수)　+ 데이터 배열" 조합을 쓰고, C 필드명을 그대로 노출하는 대신 field_labels로 한글 라벨을 붙이고, 60여 건을 list_cols = 2로 2단 배치해서 스크롤 없이 한눈에 보이게 합니다.

전문별 처리 건수

거래소 전문(메시지 타입)별 수신/처리/DB저장 건수 — 실무에서 가장 흔한 운영 모니터링 패턴입니다.

{
  label   = "전문별 처리 건수",
  view    = "manual_msgstats_cfg",
  shm_key = 0x1300,
  header  = "examples/msg_stats.h",
  struct  = "MSG_STATS.data",
  header_struct = "MSG_STATS_HEADER",
  count_field   = "cur_cnt",  -- head.cur_cnt만큼만 표시
  title = "전문별 처리 현황 (거래소 연동)",
  field_labels =
    "msg_code=전문코드,msg_name=전문명,recv_cnt=수신건수,"
    .. "proc_cnt=처리건수,db_cnt=DB저장건수",
  hide = "db_cnt",
  list_cols = 2,  -- 60건을 2단으로 나란히. SSH·웹 둘 다 동일하게 2단 분할
}

실행 화면 · list_cols=2, field_labels 적용

manual-1 · 2

같은 화면을 Lua 파일로

바로 위 8개 화면을 이번엔 file=로 엽니다. 재구현이 아닙니다 — tapas.* 바인딩이 core의 같은 C 함수를 그대로 호출해서, 화면은 1번 항목과 픽셀 단위로 동일합니다. 보통 config.lua로 시작했다가, 이 화면만의 로직(색상 임계값, 파생 컬럼 등)이 필요해지면 Lua 파일로 옮겨갑니다 — 그 과정은 manual-2에서 이어집니다. (예외: 아래 "전문별 처리 건수"는 일부러 다르게 구현 — 이유는 바로 아래 참고.)

local M = {}

function M.update()
    tapas.system_update()
end

function M.render(p)
    tapas.system_render(p)
end

return M

local M = {}

function M.update() end

-- VT_BUILTIN 전용 키 핸들러는 file= 뷰에 안 붙는다 — PgUp/PgDn을
-- config-only 쪽과 똑같이 쓰려면 스크롤 위치를 직접 들고 있어야 한다.
local scroll = 0
local last_page_size, last_total = 20, 0

function M.render(p)
    local t = tapas.view_table("process")
    last_page_size = p.rows - 1
    last_total = #t.rows
    tapas.render_table(p, 0, t.headers, t.rows, scroll)
end

function M.handle_key(key)
    local handled
    scroll, handled = tapas.scroll_key(key, scroll, last_total, last_page_size)
    return handled
end

return M

-- config-only 쪽은 SHM에 있는 msg_name 필드를 그대로 보여주지만, 이
-- 파일은 일부러 그 필드를 안 쓰고 코드→이름 매핑을 Lua 배열로 따로
-- 들고 있다가 붙여서 보여준다 — SHM에 이름이 없는 실무 상황을 흉내낸
-- 것이다. 매핑에 없는 코드는 이름 칸만 비우고, 행 자체는 그대로 보여준다.
local MSG_NAMES = {
    ORD00 = "신규주문", ORD01 = "정정주문", CHE00 = "체결통보",
    QUO00 = "현재가시세", QUO03 = "시간외단일가",
    -- ... (전체 60여 개는 manual-1/lua/lua_msgstats.lua 참고)
}

function M.render(p)
    -- SHM 구조체 뷰 엔진(tapas.shmstruct_render)은 못 쓴다 — 파싱한
    -- 필드를 그대로 보여줄 뿐 없는 값(이름)을 만들어내지 못해서, 원본만
    -- 읽고(shmstruct_read) 표는 직접 그린다.
    local rows_raw = tapas.shmstruct_read(spec)

    -- config.lua의 title=을 그대로 읽어 config-only 항목과 같은 제목을
    -- 보여준다 — 직접 그리는 만큼 제목도 직접 그려야 한다.
    tapas.render_line(p, 0, {
        { name = tapas.title(), value = string.format("%d건", #rows_raw) },
    })

    local rows = {}
    for _, r in ipairs(rows_raw) do
        table.insert(rows, {
            r.msg_code,
            MSG_NAMES[r.msg_code] or "",
            { value = r.recv_cnt, align = "right" },
            { value = r.proc_cnt, align = "right" },
            { value = r.db_cnt,   align = "right" },
        })
    end

    tapas.render_table(p, 2,
        { "전문코드", "전문명", "수신건수", "처리건수", "DB저장건수" },
        rows, 0, tapas.list_cols())
end

manual-1 · 3

화면 여러 개를 한 번에

panels = { ... }로 이미 등록된 화면 여러 개를 한 항목에 묶으면 자동으로 분할된 대시보드가 됩니다. 각 패널은 완전히 독립된 view 인스턴스라서, 위에서 이미 스크린샷으로 본 시스템 상태·SHM 구조체 같은 화면이 그대로 한 그리드 안에 나란히 그려지는 것뿐입니다 — 대시보드 전용 렌더링 엔진이 따로 있는 게 아니라, 기존 view들을 panels_cols 그리드로 배치만 다르게 합니다. 각 패널의 filter·gauge 같은 세부 설정은 그 view id로 먼저 등록된 항목(보통 "기본기능"의 항목) 값을 그대로 물려받습니다.

{
  label = "종합 현황 (4분할)",
  view  = "manual_dashboard_overview",
  panels = {
    { label = "시스템 상태", view = "system" },
    { label = "프로세스 목록", view = "process" },
    { label = "로그", view = "log" },
    { label = "SHM 구조체", view = "manual_shmstruct_dashboard",
      shm_key = 0x1234, header = "examples/koscom_stock.h",
      struct = "KOSCOM_STOCK_A0", orientation = "vertical" },
  },
}

{
  label = "종합 현황 (컬럼지정)",
  view  = "manual_dashboard_cols",
  panels_cols = 3,
  panels = {
    { label = "시스템 상태", view = "system" },
    { label = "프로세스 목록", view = "process" },
    { label = "로그", view = "log" },
    { label = "SHM 구조체", view = "manual_shmstruct_dashboard",
      orientation = "vertical" },
  },
}

종합 현황 (Lua) 항목은 같은 3개 화면을 manual-1/lua/lua_dashboard.lua로 나열한 것인데, 이 파일은 update()/render() 없이 panels = {...} 테이블만 반환합니다. 그러면 config.lua 선언 쪽과 완전히 같은 C 엔진 (view_dashboard.c)이 그리므로, gauge·filter 같은 세부 설정까지 한 글자도 안 틀리고 동일하게 나옵니다 — "Lua 파일에 로직을 다시 짜지 않고 선언만 옮겨 적어도 똑같이 동작한다"는 이 프로젝트의 원칙을 그대로 보여주는 예시입니다.

manual-1 · 4

MySQL / PostgreSQL / Altibase 조회

DB 클라이언트 라이브러리를 링크하지 않습니다 — mysql/psql/isql 같은 표준 CLI를 io.popen()으로 실행하고 그 출력을 표로 파싱해서 보여줍니다. 새 DB를 추가하고 싶으면 CLI 하나 실행할 수 있는 서버라면 바로 됩니다 — 커넥터 설치도, 재빌드도 필요 없습니다.

db_*.lua 상단 6개 값만 바꾸면 됩니다(재빌드 불필요) — 헷갈리는 건 host/port 뿐, 아래 3가지 중 하나입니다.

host = "192.168.0.50"
port = 5432

docker run -p 127.0.0.1:5432:5432 postgres

host = "127.0.0.1"
port = 5432

which psql   # 또는 mysql / isql — 클라이언트가 있는지 확인

psql -h 127.0.0.1 -p 5432 -U <user> -d <database>   # 접속 테스트

# 되면 그 값을 db_*.lua 상단에 그대로 옮기면 끝

local host     = "192.168.0.50"
local port     = 5432
local user     = "readonly_user"
local password = "s3cr3t"
local database = "sales"
local query    = "SELECT id, name, amount FROM orders LIMIT 50;"

-- MySQL 조회 뷰: mysql CLI를 io.popen()으로 실행해 결과를 표로 표시.
-- host에는 mysql CLI를 설치하지 않고, docker 컨테이너(tapas-eye-demo-mysql)
-- 안의 mysql 클라이언트를 `docker exec`로 그대로 호출한다 — TCP 접속정보
-- (host/port) 대신 컨테이너 이름을 쓴다는 점만 db_postgresql.lua와 다르다.
-- 접속정보/쿼리는 아래 값만 고치면 됨(재빌드 불필요). 비밀번호는 커맨드라인
-- 인자 대신 MYSQL_PWD 환경변수로 넘겨 `ps aux` 노출을 막는다(단
-- /proc/pid/environ로는 여전히 보일 수 있음).
--
-- 예제 쿼리는 examples/koscom_stock.h의 KOSCOM_STOCK_A3(체결) 구조체 필드 중
-- 일부(종목코드/체결가격/체결수량/시가/고가/저가)를 그대로 옮긴 테스트 테이블
-- koscom_stock_a3_test를 조회한다 — db_postgresql.lua가 쓰는 KOSCOM_STOCK_A0
-- (종목배치)와는 다른 구조체/필드라 표시되는 값도 다르다. 테이블/샘플 데이터는
-- lua/db/db_mysql_seed.sql로 만든다.
local common = dofile("lua/db/db_common.lua")

local container = "tapas-eye-demo-mysql"
local user       = "root"
local password   = ""
local database   = "test"
local query      = "SELECT isin, exec_prc, exec_qty, open_prc, high_prc, low_prc FROM koscom_stock_a3_test;"

local function build_cmd()
    return string.format(
        "docker exec -e MYSQL_PWD=%s %s mysql -u%s %s -B -e %s",
        common.shell_quote(password),
        common.shell_quote(container),
        common.shell_quote(user),
        common.shell_quote(database),
        common.shell_quote(query)
    )
end

return common.new_view({ build_cmd = build_cmd, sep = "\t", refresh_sec = 5 })

-- PostgreSQL 조회 뷰: psql CLI를 io.popen()으로 실행해 결과를 표로 표시.
-- 접속정보/쿼리는 아래 값만 고치면 됨 (재빌드 불필요). 비밀번호는 커맨드라인
-- 인자 대신 PGPASSWORD 환경변수로 넘긴다 — 더 안전한 대안은 ~/.pgpass.
--
-- 예제 쿼리는 examples/koscom_stock.h의 KOSCOM_STOCK_A0(코스피/코스닥/코넥스
-- 배치) 구조체 필드 중 일부(종목코드/한글약명/기준가/전일종가/상한가/하한가)를
-- 그대로 옮긴 테스트 테이블 koscom_stock_a0_test를 조회한다 — DB 조회 결과가
-- SHM 구조체 뷰와 같은 필드를 보여준다는 걸 확인하기 위한 예시일 뿐, 실제
-- 운영 스키마는 아니다. 테이블/샘플 데이터는 lua/db/db_postgresql_seed.sql로
-- 만든다.
local common = dofile("lua/db/db_common.lua")

local host     = "127.0.0.1"
local port     = 5432
local user     = "postgres"
local password = ""
local database = "postgres"
local query    = "SELECT isin, kor_name, base_price, prev_close, upper_limit, lower_limit FROM koscom_stock_a0_test;"

local function build_cmd()
    return string.format(
        "PGPASSWORD=%s psql -h %s -p %s -U %s -d %s -A -F %s -c %s",
        common.shell_quote(password),
        common.shell_quote(host),
        tostring(port),
        common.shell_quote(user),
        common.shell_quote(database),
        common.shell_quote("|"),
        common.shell_quote(query)
    )
end

return common.new_view({ build_cmd = build_cmd, sep = "|", refresh_sec = 5 })

-- Altibase 조회 뷰: isql CLI를 io.popen()으로 실행해 결과를 표로 표시.
-- host에는 아무것도 설치하지 않고, docker 컨테이너(tapas-eye-demo-altibase,
-- altibase/a_plus_edition — 라이선스 없이 도는 무료 에디션) 안의 isql을
-- `docker exec`로 그대로 호출한다 — db_mysql.lua와 같은 패턴.
--
-- isql은 mysql -B / psql -A 같은 "구분자 출력" 옵션이 없다(고정폭 표 +
-- 헤더밑줄 + "N rows selected." 꼬리말만 지원). 그래서 두 가지로 우회한다:
--   1. `set heading off;`로 isql 자체 헤더/밑줄을 끄고, 진짜 헤더는 우리가
--      echo로 직접 앞에 붙인다.
--   2. 쿼리 자체에서 SELECT ... || '|' || ... 로 각 행을 이미 구분자로 이어
--      붙여서 내보낸다 — isql이 남기는 컬럼 우측 공백 패딩은 sed로 벗겨낸다.
-- 결과물은 mysql/psql이 내는 것과 같은 모양(헤더 줄 + 구분자로 나뉜 데이터
-- 줄 + "N rows selected.")이 되어 db_common.lua를 그대로 재사용할 수 있다.
--
-- 예제 쿼리는 examples/msg_db_stats.h의 DB_STATS_DATA(DB적재 프로세스가
-- 전문별로 남기는 DB저장 건수) 구조체 필드(전문코드/DB저장건수)를 그대로
-- 옮긴 테스트 테이블 msg_db_stats_test를 조회한다 — db_postgresql.lua/
-- db_mysql.lua가 쓰는 koscom_stock.h(시세) 구조체들과는 다른 구조체라 값도
-- 다르다. 테이블/샘플 데이터는 lua/db/db_altibase_seed.sql로 만든다.
local common = dofile("lua/db/db_common.lua")

local container = "tapas-eye-demo-altibase"
local user       = "sys"
local password   = "manager"
local headers    = { "msg_code", "db_cnt" }
local query      = "SELECT msg_code || '|' || db_cnt FROM msg_db_stats_test;"

local function build_cmd()
    local isql_cmd = string.format(
        "$ALTIBASE_HOME/bin/isql -u %s -p %s -s localhost -silent -noprompt",
        user, password
    )
    return string.format(
        "{\necho %s\ndocker exec -i %s bash -lc %s <<'ALTIBASE_SQL'\nset heading off;\n%s\nquit;\nALTIBASE_SQL\n} | sed 's/[ \t]*$//'",
        common.shell_quote(table.concat(headers, "|")),
        common.shell_quote(container),
        common.shell_quote(isql_cmd),
        query
    )
end

return common.new_view({ build_cmd = build_cmd, sep = "|", refresh_sec = 5 })

이 페이지의 다른 예시들과 달리 이 항목은 실행 화면 스크린샷을 아직 싣지 않았습니다 — DB 조회 예제는 데모용 docker 컨테이너(MySQL/ PostgreSQL/Altibase 각각 하나씩)에 접속하는 구성이라 스크린샷이 서버쪽 인프라 변경에 따라 쉽게 낡을 수 있어서, 코드 스니펫과 표로만 안내합니다. 접속 정보만 올바르면 CLI가 출력하는 그대로(오류 메시지 포함) 표로 렌더링된다고 이해하시면 됩니다.

manual-1 · 5

SHM 3개를 하나의 표로 조인

SHM 구조체 뷰(view=)는 SHM 하나만 다룹니다. 수신·처리·DB적재가 서로 다른 프로세스라 SHM도 각자 관리되는 게 실무에선 흔한데, 이런 조인은 config.lua만으로는 안 되고 Lua가 필요합니다 — 화면을 안 그리고 데이터만 raw로 가져오는 tapas.shmstruct_read(spec) API를 씁니다.

tapas.shmstruct_read(spec)는 화면을 그리지 않고 { {필드명=값, ...}, ... } 형태의 순수 Lua 테이블 배열만 돌려줍니다 — view=가 하는 "파싱+렌더링"에서 렌더링만 뺀 것이라고 생각하면 됩니다. 이 raw 배열을 여러 개 받아다가 아래처럼 직접 합치는 로직을 짭니다.

전문별 처리 건수 (SHM 3개 조인)

manual-1/lua/lua_msgjoin.lua — 세 SHM을 msg_code 기준으로 합친다

local RECV_SPEC = { shm_key = 0x1301, header = "examples/msg_recv_stats.h",
  struct = "RECV_STATS.data", header_struct = "RECV_STATS_HEADER", count_field = "cur_cnt" }
local PROC_SPEC = { shm_key = 0x1302, header = "examples/msg_proc_stats.h",
  struct = "PROC_STATS.data", header_struct = "PROC_STATS_HEADER", count_field = "cur_cnt" }
local DB_SPEC   = { shm_key = 0x1303, header = "examples/msg_db_stats.h",
  struct = "DB_STATS.data",   header_struct = "DB_STATS_HEADER",   count_field = "cur_cnt" }

function M.render(p)
    local recv = tapas.shmstruct_read(RECV_SPEC)
    local proc = tapas.shmstruct_read(PROC_SPEC)
    local db   = tapas.shmstruct_read(DB_SPEC)

    -- msg_code로 세 SHM을 합친다 (등장 순서를 보존)
    local by_code, order = {}, {}
    local function row_for(code)
        if not by_code[code] then
            by_code[code] = { recv_cnt = "0", proc_cnt = "0", db_cnt = "0" }
            table.insert(order, code)
        end
        return by_code[code]
    end
    for _, r in ipairs(recv) do row_for(r.msg_code).recv_cnt = r.recv_cnt end
    for _, r in ipairs(proc) do row_for(r.msg_code).proc_cnt = r.proc_cnt end
    for _, r in ipairs(db)   do row_for(r.msg_code).db_cnt   = r.db_cnt   end

    local rows = {}
    for _, code in ipairs(order) do
        local v = by_code[code]
        table.insert(rows, { code,
            { value = v.recv_cnt, align = "right" },
            { value = v.proc_cnt, align = "right" },
            { value = v.db_cnt,   align = "right" },
        })
    end

    tapas.render_table(p, 1,
        { "전문코드", "수신건수 (SHM_A)", "처리건수 (SHM_B)", "DB저장건수 (SHM_C)" },
        rows, 0, tapas.list_cols())
end

실행 화면 · SHM 3개 조인 결과

manual-1 · 6

화면에서 SHM 값을 바로 수정 — editable_fields

지금까지 본 SHM 화면은 전부 읽기 전용이었습니다. 하지만 로그 레벨처럼 "다른 프로세스가 SHM에 남겨둔 값을, 그 프로세스를 재시작하지 않고 운영자가 그 자리에서 바로 바꾸고 싶은" 값도 실무에 흔합니다. editable_fields에 화이트리스트로 올린 필드만, 화면에서 Enter로 커서를 두고 값을 입력하면 즉시 그 SHM에 write됩니다 — 나머지 필드는 그대로 읽기 전용으로 보호됩니다.

{
  label   = "런타임 설정값 (config)",
  view    = "manual_ctrl_cfg",
  shm_key = 0x1350,
  header  = "examples/loglevel_ctrl.h",
  struct  = "LOGLEVEL_CTRL",
  editable_fields = "loglevel",  -- 이 필드만 Enter로 값 수정 가능
  title = "런타임 설정값 (SHM, loglevel만 값 직접 수정 가능)",
  field_labels =
    "loglevel=로그레벨(0~3),max_conn=최대연결수(읽기전용),"
    .. "service_name=서비스명(읽기전용)",
  filter = "",
}

local spec = {
  shm_key = 0x1350,
  header  = "examples/loglevel_ctrl.h",
  struct  = "LOGLEVEL_CTRL",
}

function M.update()
  tapas.shmstruct_update(spec)
end

function M.render(p)
  tapas.shmstruct_render(p, spec)
end

function M.handle_key(key)
  return tapas.shmstruct_handle_key(key)
end
-- editable_fields는 이 spec이 아니라 config.lua 메뉴 항목 쪽에
-- 지정합니다(위 config 예시와 동일한 자리) — Lua spec 테이블에
-- 넣어도 효과가 없습니다.

manual-1 · 7

config.lua를 화면에서 직접 편집

지금까지는 화면에 무엇을 보여줄지를 config.lua 파일을 직접 열어 텍스트로 정의했습니다. 설정 편집기는 그 config.lua 자체를 화면에서 편집합니다 — 항목 추가·삭제·순서 변경, label/hotkey/filter/gauge 같은 필드 수정까지 전부 화면 안에서 됩니다. 웹 브라우저와 SSH TUI 양쪽에 각각 있습니다.

# Ctrl 조합 표기(개요 참고) — macOS에서 F11이 OS 단축키에 가로채이는 게
# 실측 확인돼서 이 데모는 기본값을 F-키 대신 Ctrl+E로 씀
config_editor_key = "Ctrl+E"

manual-1 · 8

웹 서비스 켜고 끄기

브라우저 대시보드는 세 가지 방법 중 아무거나로 켤 수 있고, 셋 다 같은 config.lua/화면 코드를 그대로 씁니다 — 웹용으로 뭘 따로 만들 필요는 없습니다.

web_port = 8000
-- web_bind = "127.0.0.1"  -- 생략하면 0.0.0.0(모든 인터페이스)

-- menus 안에 추가
{
    label = "웹 서비스",
    web = false,  -- 웹 화면에서 웹 서버 자기 자신을 껐다 켰다 하는 건
                  -- 의미가 없음(끄면 보고 있던 그 화면도 끊김)
    items = {
        { label = "시작", action = "web_start" },
        { label = "중지", action = "web_stop" },
    },
},

tmux new-session -d -s tapas-web \
    './bin/tapas-eye --web-port 8080'

# 나중에 들여다보기
tmux attach -t tapas-web
# 끌 때
tmux kill-session -t tapas-web

location /demo/ {
    proxy_pass http://127.0.0.1:8081/;   # 트레일링 슬래시로 /demo/ 접두사를 벗겨서 전달
    proxy_set_header Host $host;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

데이터 가공하기

core가 이미 수집해 둔 데이터를 tapas.view_table()/tapas.system_read()로 그대로 가져다가, 화면 입맛에 맞게 가공만 합니다. "새로 뭘 만든다"보다 "이미 있는 걸 가져다 쓴다"에 가깝습니다 — config.lua 선언만으로는 안 되지만, Lua 몇 줄이면 되는 수준입니다. 아래 세 예제는 전부 같은 데이터 구조를 읽고 씁니다 — 그 구조를 먼저 알아두면 세 예제가 왜 그렇게 짧은지 이해가 됩니다.

function M.render(p)
    local t = tapas.view_table("process")

    -- 원본 헤더 뒤에 파생 컬럼 하나만 추가한다
    local headers = {}
    for i, h in ipairs(t.headers) do headers[i] = h end
    table.insert(headers, "CPU+MEM")

    local rows = {}
    for i, row in ipairs(t.rows) do
        local new_row = {}
        for j, cell in ipairs(row) do new_row[j] = cell end
        local cpu = tonumber(row[3].value) or 0
        local mem = tonumber(row[4].value) or 0
        table.insert(new_row, string.format("%.1f", cpu + mem))
        rows[i] = new_row
    end

    tapas.render_table(p, 0, headers, rows, scroll, tapas.list_cols())
end

local WARN_CPU, DANGER_CPU = 1.0, 5.0

function M.render(p)
    local t = tapas.view_table("process")
    local rows = {}
    for i, row in ipairs(t.rows) do
        local new_row = {}
        for j, cell in ipairs(row) do new_row[j] = cell end

        local cpu = tonumber(row[3].value) or 0
        local color = "normal"
        if cpu >= DANGER_CPU then color = "danger"
        elseif cpu >= WARN_CPU then color = "warn" end
        new_row[3] = { value = row[3].value, color = color }

        rows[i] = new_row
    end
    tapas.render_table(p, 0, t.headers, rows, scroll, tapas.list_cols())
end

function M.render(p)
    local sys   = tapas.system_read()
    local queue = tapas.view_table("queue")
    local disk  = tapas.view_table("disk")

    local rows = {
        { name = "CPU 사용률", value = string.format("%d%%", sys.cpu_pct) },
        { name = "메모리 사용률",
          value = string.format("%d%% (%d/%dMB)", sys.mem_pct, sys.mem_used_mb, sys.mem_total_mb) },
        { name = "로드 애버리지",
          value = string.format("%.2f / %.2f / %.2f", sys.load1, sys.load5, sys.load15) },
        { name = "메시지 큐 개수", value = tostring(#queue.rows) },
        { name = "디스크 마운트 수", value = tostring(#disk.rows) },
    }
    tapas.render_kv(p, rows, 0, tapas.list_cols())
end

진짜 프로그램 만들기

데이터를 가져다 가공하는 수준을 넘어, 이 화면만의 로직 — 상태를 들고 이력을 쌓거나, 이동평균·연속 횟수 같은 판단을 직접 계산하는 것 — 을 실제로 프로그래밍합니다. tapas.*는 원시값만 주고, "판단"은 전부 이 파일이 알고리즘으로 짠 것입니다.

4이력 저장해서 그래프 그리기

config.lua는 "지금 이 순간의 값"만 다룹니다. 추이를 보여주려면 매 갱신마다 값을 어딘가에 쌓아야 하는데, Lua 모듈의 최상위(local history_cpu = {})에 저장하면 그 값이 update()와 render() 호출 사이, 그리고 다음 갱신 때까지 계속 유지됩니다 — 파일이나 DB 없이 메모리 안에서 최근 MAX_POINTS개만 들고 있는 링 버퍼 역할입니다.

4이력 저장해서 그래프 그리기

manual-2/lua/lua_step4_history_graph.lua

local MAX_POINTS = 60
local history_cpu, history_mem = {}, {}  -- 모듈 최상위 = update()/render() 사이 유지

function M.update()
    local sys = tapas.system_read()
    table.insert(history_cpu, sys.cpu_pct)
    table.insert(history_mem, sys.mem_pct)
    if #history_cpu > MAX_POINTS then table.remove(history_cpu, 1) end
    if #history_mem > MAX_POINTS then table.remove(history_mem, 1) end
end

function M.render(p)
    local charts = {
        { name = "CPU %", values = history_cpu, max = 100, warn_at = 0.6, danger_at = 0.85 },
        { name = "MEM %", values = history_mem, max = 100, warn_at = 0.6, danger_at = 0.85 },
    }
    tapas.render_linegraph(p, 0, charts, 8, "area")
end

실행 화면 · render_linegraph(..., "area")

5평균 대비 급등 감지 알람

이동평균과 연속 초과 횟수를 직접 계산해서, 순간 튐은 걸러내고 진짜 경보만 잡습니다. SPIKE_RATIO(이동평균의 몇 배부터 "튐"으로 볼지), MIN_BASELINE(이 평균 이상일 때만 판단 — 평소 값이 거의 0인 지표가 사소한 변화에도 경보를 울리는 걸 방지), ALERT_AFTER(몇 틱 연속으로 튀어야 진짜 ALERT로 볼지) 세 상수만 화면마다 다르게 조정하면 됩니다.

5평균 대비 급등 감지 알람

manual-2/lua/lua_step5_anomaly_alert.lua

local SPIKE_RATIO, MIN_BASELINE, ALERT_AFTER = 1.5, 5, 3
local history, streak = {}, 0

function M.update()
    local sys = tapas.system_read()
    table.insert(history, sys.cpu_pct)
    if #history > 30 then table.remove(history, 1) end
end

function M.render(p)
    local cur = history[#history] or 0
    local sum = 0
    for _, v in ipairs(history) do sum = sum + v end
    local avg = #history > 0 and (sum / #history) or 0

    local spiking = avg >= MIN_BASELINE and cur >= avg * SPIKE_RATIO
    streak = spiking and (streak + 1) or 0

    local status, color = "정상", "good"
    if streak >= ALERT_AFTER then status, color = "ALERT", "danger"
    elseif spiking then status, color = "감시중", "warn" end

    tapas.render_table(p, 0,
        { "현재 CPU%", "이동평균(30틱)", "평균 대비", "연속 초과", "상태" },
        { { string.format("%.1f", cur), string.format("%.1f", avg),
            string.format("%+.0f%%", avg > 0 and (cur - avg) / avg * 100 or 0),
            tostring(streak), { value = status, color = color } } })
end

실행 화면 · 현재 상태: 정상 (급등 없음)

두 화면 모두 원시값은 tapas.system_read() 하나뿐입니다. "이력을 쌓는다", "이동평균과 연속 횟수로 진짜 경보를 가려낸다"는 로직 자체가 config.lua로는 표현할 수 없는 영역이고, 이게 Lua 파일이 필요한 진짜 이유입니다.

C로 직접 짜기

tapas-eye의 진짜 강점입니다: Lua 표준 라이브러리(os/io/ string/table/math)에 없는 시스템 콜 — statvfs(), msgget()/msgctl() 같은 — 이 필요한 순간, C 함수 하나를 짜서 .so로 컴파일하고 Lua의 require()로 불러 쓰면 끝입니다. tapas.* API 자체가 이 방법(표준 Lua C 모듈)으로 만들어져 있고, 사용자 플러그인도 완전히 같은 규약·같은 헤더(tapas_plugin.h)로 tapas.*와 동등한 자격으로 동작합니다.

플러그인은 크게 두 패턴으로 나뉩니다 — 어느 쪽을 고르느냐에 따라 SSH 터미널에서만 동작하는지, 웹 대시보드에서도 동작하는지가 갈립니다.

#include "tapas_plugin.h"
#include <sys/statvfs.h>

static int l_gb(lua_State *L) {
    const char *path = luaL_checkstring(L, 1);

    struct statvfs st;
    if (statvfs(path, &st) != 0) {
        lua_pushnil(L);
        return 1;
    }

    double free_bytes = (double)st.f_bsize * (double)st.f_bavail;
    lua_pushnumber(L, free_bytes / (1024.0 * 1024.0 * 1024.0));
    return 1;
}

static const luaL_Reg funcs[] = { {"gb", l_gb}, {NULL, NULL} };

int luaopen_disk_free(lua_State *L) {
    luaL_newlib(L, funcs);
    return 1;
}

Lua에서 사용하기

컴파일된 .so는 평범한 Lua 모듈과 똑같이 require()로 불러옵니다. C였다는 흔적은 여기서부터 전혀 남지 않습니다 — disk_free.gb(path)는 Lua로 작성한 다른 함수와 호출 문법이 동일합니다.

6manual-2/lua/lua_step6_c_library.lua — Lua에서 사용

require()로 불러오면 그 뒤로는 평범한 Lua 함수처럼 씁니다.

-- plugins/*.so는 require()가 자동으로 찾는다
-- (lua_conf.c가 package.cpath에 './plugins/?.so'를 미리 넣어둔다)
local disk_free = require("disk_free")

local PATHS = { "/", "/tmp", "/var" }

function M.render(p)
    local rows = {}
    for _, path in ipairs(PATHS) do
        local gb = disk_free.gb(path)
        table.insert(rows, {
            name = path,
            value = gb and string.format("%.1f GB 여유", gb) or "경로 없음",
        })
    end
    tapas.render_kv(p, rows)
end

실행 화면 · disk_free.gb()로 조회한 실제 여유 공간

패턴 B — C가 화면까지 직접 그리기, 그리고 왜 웹에서는 안 보이나

plugins/example_view.c는 tapas.render_*()를 거치지 않고 tui_move()/tui_color()/tui_puts()로 패널에 직접 글자를 씁니다 — 함수 하나로 끝나는 만큼 빠르지만, 아래 코드를 보면 알 수 있듯 TapasPanel의 row/col을 기준으로 좌표를 손수 계산해야 합니다.

#include "tapas_plugin.h"
#include <time.h>

static char s_time[32];
static int  s_tick = 0;

static int l_update(lua_State *L) {
    (void)L;
    time_t t = time(NULL);
    strftime(s_time, sizeof(s_time), "%Y-%m-%d %H:%M:%S", localtime(&t));
    s_tick++;
    return 0;
}

static int l_render(lua_State *L) {
    TapasPanel p = tapas_panel_from_lua(L, 1);

    tui_move(p.row + 1, p.col + 2);
    tui_color(TAPAS_CLR_HEADER);
    tui_puts("[ Example Plugin v1.0 ]");
    tui_clear_line();

    tui_move(p.row + 4, p.col + 4);
    tui_color(TAPAS_CLR_NORMAL);
    tui_printf("현재 시각  : %s", s_time);
    tui_clear_line();

    tui_color(TAPAS_CLR_RESET);
    return 0;
}

static const luaL_Reg funcs[] = {
    {"update", l_update}, {"render", l_render}, {NULL, NULL}
};

int luaopen_example_view(lua_State *L) {
    luaL_newlib(L, funcs);
    return 1;
}

세 번째 예시 — msgq_depth.c: 커널이 이미 아는 값은 다시 파싱하지 않는다

scenarios/ab-pipeline의 큐 대기 건수 컬럼이 실제로 쓰는 플러그인입니다. /proc/sysvipc/msg 텍스트를 파싱하는 대신 msgget() + msgctl(IPC_STAT)으로 커널이 이미 추적 중인 msg_qnum을 직접 읽습니다 — disk_free.c와 똑같이 패턴 A(값만 반환)라서 SSH·웹 어느 쪽에서 봐도 동일하게 나옵니다.

#include "tapas_plugin.h"
#include <sys/ipc.h>
#include <sys/msg.h>

static int l_read(lua_State *L) {
    long key = (long)luaL_checkinteger(L, 1);

    int msqid = msgget((key_t)key, 0);
    if (msqid < 0) { lua_pushnil(L); return 1; }

    struct msqid_ds ds;
    if (msgctl(msqid, IPC_STAT, &ds) != 0) { lua_pushnil(L); return 1; }

    lua_pushinteger(L, (lua_Integer)ds.msg_qnum);
    return 1;
}

static const luaL_Reg funcs[] = { {"read", l_read}, {NULL, NULL} };

int luaopen_msgq_depth(lua_State *L) {
    luaL_newlib(L, funcs);
    return 1;
}

scenarios/ab-pipeline/lua/view_ab_queue.lua는 파이프라인 하나당 SHM(tapas.shmstruct_read) + 파일(io.open) + msgq_depth.read(pl.msgq_key) 세 소스를 한 행에 조합해서 표로 보여줍니다 — 소스가 SHM이든 파일이든 C 플러그인이든, Lua 쪽에서 보면 그냥 "값 하나 돌려주는 함수" 셋을 조합하는 것과 다르지 않습니다.