선을 넘는 개발 로그

API 쉽게 이해하기 — 식당 주문서로 알아보는 서비스 연결

목차주방에는 손님이 들어갈 수 없습니다주문서에 칸이 정해져 있는 이유메뉴에 없는 것은 시킬 수 없습니다연결하는 데 왜 시간이 걸릴까요맺음말오늘은 개발을 하면서 자주 듣는 API에 대해서 간단하게 다뤄보도록 하겠습니다. 소프트웨어 개발자가 아니라도 API 는 종종 들리는 단어일 것 같습니다. API 는 다방면에서 사용하는 용어이긴 하지만, 웹 개발에서의 API 란 어떤 의미인지 단순히 식당에서 주문하는 걸로 비유해서 설명을 해보도록 하겠습니다.주방에는 손님이 들어갈 수 없습니다식당에서 밥을 먹을 때 우리는 주방에 직접 들어가지 않습니다. 자리에 앉아 주문하면 잠시 뒤 음식이 나옵니다. 주방이 어떻게 생겼는지, 불을 얼마나 세게 쓰는지 몰라도 밥은 먹을 수 있습니다. 프로그램끼리도 똑같습니다. 지도를 보여..

Claude Design 쉽게 이해하기 — 말로 부탁하면 화면이 나오는 도구

목차그림 잘 그리는 친구가 생겼습니다예전에는 왜 어려웠을까요어떻게 부탁하고, 어떻게 고칠까요친구도 못하는 일이 있습니다맺음말그림 잘 그리는 친구가 생겼습니다학교 다닐 때 그림을 유난히 잘 그리는 친구가 한 명쯤 있었습니다. 머릿속에 있는 걸 말로 설명하면 "아, 이런 거?" 하면서 슥슥 그려 주던 친구요. 내가 붓을 못 잡아도, 그 친구에게 설명만 잘하면 원하는 그림이 나왔습니다.Claude Design(클로드 디자인)은 컴퓨터 안에 그런 친구를 한 명 앉혀 둔 것과 비슷합니다. 만들고 싶은 화면을 말로 설명하면 그 자리에서 그려서 보여 줍니다. 마음에 안 드는 곳이 있으면 "여기는 좀 크게 해 줘"라고 말하면 고쳐 줍니다.이 글은 개발도 디자인도 해 본 적 없는 분을 위해 썼습니다. 어려운 말은 쓰지 ..

Prometheus란 무엇인가 — 등장 배경과 지표 수집 기본 활용법

목차개요Prometheus는 어떤 문제를 풀려고 등장했나구성 요소와 지표 모델Spring Boot에 붙이는 기본 활용법맺음말개요한 줄 정의와 이 글의 범위Prometheus(프로메테우스)는 시계열 지표를 주기적으로 수집해 저장하고, 질의 언어로 조회하며, 임계 조건을 넘으면 알림을 보내는 오픈소스 모니터링 시스템입니다. 2012년 SoundCloud에서 시작해 현재는 CNCF(Cloud Native Computing Foundation) 재단 프로젝트이며, 쿠버네티스 환경의 사실상 기본 모니터링 도구로 쓰이고 있습니다.이 글에서 다루는 것다루지 않는 것왜 등장했는지, 기존 방식과 무엇이 다른지고가용성·장기 보관 구성(Thanos, Mimir)구성 요소와 지표 타입, PromQL 기본Grafana 대시보드..

목차개요실행 여부는 왜 별도 신호인가무실행 임계 설계 — 주기·유예·판정식오탐과 미탐을 가르는 예외 설계맺음말개요문제 배경모니터링 대시보드 대부분은 "실행된 것"에 대해서만 말합니다. 에러율, 응답 시간, 실패 건수는 모두 무언가가 실행되었다는 전제 위에서 계산되는 지표입니다. 그래서 정작 아무 일도 일어나지 않은 장애, 즉 무실행 장애는 대시보드가 가장 조용할 때 진행됩니다. 정산 배치가 스케줄러 노드 재기동 이후 등록되지 않아 사흘째 돌지 않아도 에러 로그는 한 줄도 남지 않고, 상류 시스템이 호출을 끊어 API 트래픽이 0이 되어도 5xx는 0건이라 알림이 울리지 않습니다.실패는 신호를 남기지만, 아예 실행되지 않은 작업은 아무 신호도 남기지 않습니다. 침묵은 정상과 구분되지 않습니다.무실행 감지는..

목차같은 부탁인데 결과가 다릅니다짧은 부탁은 상대가 빈칸을 채웁니다빈칸을 대신 채워 주는 네 가지한 번에 끝내지 않는 것이 정상입니다맺음말같은 부탁인데 결과가 다릅니다옆자리 사람은 AI에게 부탁해 쓸 만한 것을 받아 옵니다. 저는 같은 것을 부탁했는데 엉뚱한 것이 나옵니다. 화면도 같고 도구도 같은데 결과만 다릅니다. 이럴 때 흔히 "요령이 있나 보다" 하고 넘기게 됩니다.이 차이는 한 번 쓰고 마는 일이라면 대수롭지 않지만, 매일 쓰기 시작하면 빠르게 벌어집니다. 같은 시간을 들이고도 한쪽은 고쳐 쓸 것을 받고 다른 쪽은 버릴 것을 받기 때문입니다.요령이라기보다 부탁하는 방식의 차이입니다. AI에게 건네는 그 말을 프롬프트(prompt), 우리말로 하면 지시문이라고 부르는데, 이 글은 지시문을 잘 쓰는..

목차개요GitHub Actions OIDC의 동작 원리AWS IAM Identity Provider 및 역할 설정GitHub Actions 워크플로우 구현보안 강화와 트레이드오프운영 환경 적용 시 고려사항맺음말개요문제 배경GitHub Actions에서 AWS에 애플리케이션을 배포할 때 가장 먼저 마주치는 질문은 "어떻게 인증할 것인가"입니다. 수년간 가장 널리 쓰인 방법은 AWS IAM 사용자를 생성하고, 그 액세스 키와 시크릿 키를 GitHub Secrets에 저장한 뒤 워크플로우에서 환경 변수로 주입하는 방식이었습니다. 이 접근법은 간단하고 즉각 동작하지만, 장기 자격 증명(long-lived credentials)이라는 본질적인 위험을 안고 있습니다. 여기서 장기 자격 증명이란 한 번 발급하면 사람..

목차개요BGE-M3가 만들어내는 세 가지 표현무엇을 색인하고 무엇을 버릴 것인가청킹과 인코딩 설계벡터 인덱스와 검색 결합운영 환경에서 확인할 것들맺음말개요문제 배경: 키워드 검색과 벡터 검색은 서로 다른 곳에서 실패합니다검색 품질을 올리려고 임베딩을 도입했는데 정확히 매칭돼야 할 질의가 오히려 나빠지는 경험은 흔합니다. BGE-M3는 이 문제를 하나의 모델 안에서 다루기 위해 만들어진 다국어 임베딩 모델이며, 밀집 벡터(Dense)·희소 가중치(Sparse)·토큰 단위 다중 벡터(Multi-Vector)를 한 번의 인코딩으로 동시에 산출합니다. 색인 설계의 출발점은 이 세 가지 중 무엇을 저장하고 무엇을 검색 시점에 계산할지 정하는 일입니다.두 방식이 어디서 무너지는지 보면 왜 결합이 필요한지가 분명해집..

목차개요컬럼 지향 저장이 만드는 차이ClickHouse의 내부 구조속도를 위해 포기한 것들언제 고르고 언제 고르지 않는가맺음말개요문제 배경: 집계 쿼리가 감당이 안 되는 시점ClickHouse는 대용량 데이터의 집계 쿼리를 빠르게 처리하기 위해 만들어진 오픈소스 컬럼 지향(Column-Oriented) 데이터베이스입니다. 이름은 들어봤지만 "우리 PostgreSQL로도 잘 돌아가는데 굳이?"라는 단계에서 멈춰 있는 경우가 많습니다. 그 질문은 보통 서비스가 어느 규모를 넘어가면서 저절로 풀립니다. 이벤트 로그가 수억 건을 넘고, 운영진이 보는 대시보드 하나가 30초씩 걸리고, 그 쿼리 하나가 돌 때마다 서비스 트랜잭션까지 같이 느려지는 시점입니다.이때 흔히 나오는 처방들은 각자 유효하지만, 공통된 한계를..

개요JSON-LD 구조화 데이터는 페이지 안의 정보를 검색엔진이 그대로 이해하도록 붙이는 표준화된 메타데이터입니다. 그런데 SPA(Single Page Application)는 이 데이터를 심어도 크롤러가 못 읽는 경우가 있습니다. 데이터를 JS가 브라우저에서 받아 그리기 때문에, 크롤러가 처음 받는 HTML에는 아무 콘텐츠도 없기 때문입니다.전국 클래식 공연장의 일정을 모아 보여주는 개인 사이드 프로젝트(클래식 공연 캘린더)에서 이 문제를 겪었습니다. Vite + TypeScript로 만든 SPA라 첫 HTML에는 공연이 하나도 없었고, Search Console에는 색인이 거의 잡히지 않았습니다.이 글은 JSON-LD 구조화 데이터를 빌드 시점에 심어 이 문제를 해결한 과정을 정리합니다. 개념보다는 ..

목차들어가며 1. 증상 — 반쪽만 저장된 데이터2. 코드를 다 뒤졌는데 아무 문제가 없었습니다3. 용의자는 코드가 아니라 실행 환경이었습니다4. 스레드가 들고 있는 것 — 그림 두 장으로 보는 차이5. 왜 로그 한 줄 안 남았을까 — 침묵의 메커니즘6. 추측을 멈추고 자를 만들었습니다7. 실측 — 같은 WAR, 옵션 하나만 토글8. 잔재 지도 — 어디서 터졌느냐에 따라 남는 게 달랐습니다9. 수정은 한 줄이었습니다10. 고치고 나니 새로 생긴 걱정들11. 남은 이야기와 배운 것들어가며@Transactional은 개발하면서 가장 의심을 안 하게 되는 어노테이션 중 하나입니다. 붙여두면 예외가 났을 때 알아서 되돌려주니까요. 저도 그렇게 믿고 몇 년을 살았습니다.그런데 운영에서 이런 데이터가 나오기 시작했습..