MSA 환경에서의 API 문서화는 어떤 식으로 구성하는 걸까? 예컨대, 모듈이 10개 있다고 하면 각 모듈마다 API 문서가 만들어질 테고 API 문서를 클라이언트에 제공하기 위해서 각각의 (10개의) URL를 전달해야 할 텐데 이게 과연 효율적일까? 물론 기능별로 URL이 분리된다는 장점이 있고 굳이 모아보자면 각 API 문서를 다시 한번 크롤링 하여 검색할 수 있도록 제공하는 것도 하나의 방법이 될 수 있다. 하지만 이러한 방법들은 요구 사항을 위한 별도의 작업을 하게 되니 일을 위한 일이 되는 것 같아 뭔가 아쉬웠다. 좋은 방법이 없을까?

고민의 시작

　한창 궁금증이 머릿속에서 지워지지 않았을때 Spring 한국 스프링 사용자 모임 페이스북 그룹에 문의도 해가며 방법을 찾아가고 있었다.

　필자와 함께 개발자의 인생을 시작한 멋진 친구들에게 정확히 올해 6월 초에 고민을 털어놓으며 좋은 방법이 없을지에 대한 논의를 했던 적이 있다. 그런데 친구 중 한 명이 잊고 있었던 그 이슈에 대해서 다시 꺼내며 URL 하나를 던져준다. 참 고마운 친구들.

Shout out 34. asuraiv, black9p

　올해 NHN FORWARD에서 진행했던 세션 중에서 MSA 환경에서 API 문서 관리하기: 생성부터 배포까지라는 제목의 내용이었고, 정확하게 필자가 고민했던 부분을 콕! 집어서 해결해 준 사례였다. 역시 세상엔 엄청난 고수들이 내가 고민했던 부분들을 이미(혹은 이후에라도) 고민하고 해결한 경우가 많다는 것을 느끼고 공유의 힘이 이렇게도 대단하구나 하며 놀라움을 금치 못하였다.

　이번 포스팅에서는 OpenAPI Spec 을 활용하여 Spring Restdocs로 만들어지는 문서를 Swagger UI에서 보는 흐름을 실제로 구현해 보고자 한다. 즉, Swagger 나 Spring Restdocs 뭐로 만들든 간에 OpenAPI Spec에 맞춰서만 만든다면 한곳에서 볼 수 있겠다는 희망이 보였다. 며칠 전 작성한 OpenAPI 와 Swagger-ui 포스팅을 본 독자들은 지금의 포스팅을 작성하기 위한 밑거름이었다는 사실을 눈치챘을 수도 있을 것 같다.

좋은 내용을 공유해 주신 (저의 고민을 완벽하게 해결해 주신) NHN FORWARD 발표자분께 이 포스팅을 빌어 감사의 인사를 보냅니다. :) 당장 팀 내에도 적용해봐야겠어요!!

Spring Restdocs에서 OpenAPI Spec 추출

　누가 또 친절하게 오픈소스로 만들어놨다. https://github.com/ePages-de/restdocs-api-spec 에서 관련 내용을 확인할 수가 있는데 해당 링크에서는 gradle 버전이고 https://github.com/BerkleyTechnologyServices/restdocs-spec 는 maven 버전이라고 한다. 마침 필자의 Github에 Maven 버전으로 SpringRestdocs를 세팅해둔 Repository 가 있어서 이를 활용해보고자 한다.

pom.xml 추가

　관련 dependency를 추가하자. jcenter라고 bintray.com 에서 운영되는 Maven Repository에 올려진 오픈소스이니 repository 도 추가해 주자.

<properties>
	<restdocs-api-spec.version>0.10.0</restdocs-api-spec.version>
	<restdocs-spec.version>0.19</restdocs-spec.version>
</properties>

<repositories>
	<repository>
		<id>jcenter</id>
		<url>https://jcenter.bintray.com</url>
	</repository>
</repositories>

<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-api-spec</artifactId>
	<version>${restdocs-api-spec.version}</version>
	<scope>test</scope>
</dependency>

<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-api-spec-mockmvc</artifactId>
	<version>${restdocs-api-spec.version}</version>
	<scope>test</scope>
</dependency>

위의 dependency에서 제공해 주는 모듈로 테스트의 SpringRestdocs를 만들었다면 OpenAPI Spec 을 만들어 주는 plugin 또한 추가해 주자

<pluginRepositories>
	<pluginRepository>
		<id>jcenter</id>
		<url>https://jcenter.bintray.com</url>
	</pluginRepository>
</pluginRepositories>

<plugin>
	<groupId>com.github.berkleytechnologyservices.restdocs-spec</groupId>
	<artifactId>restdocs-spec-maven-plugin</artifactId>
	<version>${restdocs-spec.version}</version>
	<executions>
		<execution>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<specification>OPENAPI_V3</specification>
				<format>JSON</format>
				<outputDirectory>${project.build.directory}/classes/static/docs</outputDirectory>
			</configuration>
		</execution>
	</executions>
</plugin>

위 plugin 설정을 보면 format 을 JSON으로 한 것을 볼 수 있는데 YAML로도 만들 수 있다. 자세한 사용방법은 위에서 명시한 링크를 참고해보는 게 좋을 것 같다.

　API를 개발하고 사용방법에 대한 명세를 작성하는 방법은 여러 가지가 있다. 가장 심플하게 개발 코드와는 별도로 직접 수기로 작성하여 파일 혹은 문서 링크를 전달하는 방법이 있다. 하지만 개발 코드와 별도로 직접 작성을 한다는 점에서 오타/실수가 발생할 수 있고 최신화가 안되는 여러 가지 문제가 발생한다. 그에 등장한 API 문서화 자동화 툴의 양대 산맥인 SpringRestDocs 와 Swagger.

　과거 SpringRestDocs 에 대한 포스팅을 했기에 이번엔 Swagger에 대한 사용방법에 대해 정리해보고자 한다. 이 둘의 장단점은 너무 뚜렷하기에 API문서를 제공하는 상황에 따라 적절하게 선택하여 사용할 수 있었으면 좋겠다.

SpringBoot에 Swagger 적용

　기본 SpringBoot 가 셋팅되어 있다는 가정하에 Swagger 관련 dependency를 추가해주자. 아참, 이제부터의 프로젝트 셋팅은 Gradle로 하려한다. (물론 Maven으로 해도 무방하지만…)

dependencies {
    implementation "io.springfox:springfox-boot-starter:3.0.0"
}

　이후 JavaConfig 을 아래와 같이 설정하는데 아래 내용은 아주 기본 세팅이니 자세한 내용은 공식 도큐문서를 참고해 보면 좋을 것 같다. (물론 샘플 프로젝트를 만들며 필요할 것 같은 내용은 아래에서 설명하겠다.)

@EnableSwagger2
@Configuration
public class SwaggerConfig {

	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
			.select()
			.apis(RequestHandlerSelectors.any())
			.paths(PathSelectors.any())
			.build();
	}
}

　테스트할 컨트롤러를 아래처럼 심플하게 작성하고(사칙연산…) 실행을 시킨 후 /swagger-ui/에 접속을 해보면 swagger 관련 javaConfig 하나만 추가했는데 문서가 만들어진 것을 확인할 수 있다. (http method는 편의상 다양하게 작성했으니 왜 DELETE 인가라는 의문은 접어두자.)

@RestController
public class SampleController {

	@GetMapping(value = "/addition")
	public Integer addition(Integer num1, Integer num2) {
		return num1 + num2;
	}

	@PostMapping(value = "/subtraction")
	public Integer subtraction(Integer num1, Integer num2) {
		return num1 - num2;
	}

	@PutMapping(value = "/multiplication")
	public Integer multiplication(Integer num1, Integer num2) {
		return num1 * num2;
	}

	@DeleteMapping(value = "/division")
	public Integer division(Integer num1, Integer num2) {
		return num1 / num2;
	}
}

　위에서 했던 설정들 중 몇 가지만 좀 더 자세히 살펴보자.

이외에도 security 나 공통으로 사용되는 파라미터 등 다양한 옵션을 설정할 수 있으니 가능하면 상황에 맞게 설정을 변경해 보는 것도 좋을 것 같다. 다른 설정들을 추가시켜서 좀 더 친절하게 만들어 보면 아래처럼 만들 수 있고 해당 코드는 Github에서 확인 가능하다.

OpenAPI

　Swagger 공식 홈페이지를 이리저리 둘러보면 OpenAPI라는 내용이 많이 나온다. 그렇다면 OpenAPI는 무엇일까? 문서에 나와있는 내용을 직역해보면 Swagger 사양으로 알려져 있으며 RESTful 웹 서비스를 설명, 생성, 소비 및 시각화하기 위한 기계 판독 가능 인터페이스 파일에 대한 사양이라고 한다. 즉, API 자체를 설명하는 인터페이스 스펙이라고 이해를 해볼 수 있다. 위에서 만들어졌던 Swagger를 보면 http://localhost:8080/v2/api-docs?group=Test API 라고 나와있는데 이를 클릭해보면 아래와 같이 json 형태로 보인다. 다시 보면 우리가 이제까지 Swagger으로 만든 API 문서를 설명하는 인터페이스 스펙으로 이해할 수 있다. (꽤 길어서 덧셈 API를 제외하고 지웠다.) 그렇다면 이 JSON 파일을 어떻게 활용할 수 있을까?

　관리하는 URL이 200응답을 주고 있는지 모니터링을 한다고 가정해보자. 다양한 방법이 생각나겠지만 가장 처음으로 떠오른 건 단연 Jenkins. 간단하게 사용할 언어에 맞춰 Execute Script를 작성하고 스케줄링을 걸어 놓으면 큰 수고 없이 모니터링을 구성할 수 있게 된다. 아래는 python script로 작성해 보았다.

import requests
url="http://모니터링url"
status_code = requests.get(url).status_code
if status_code != 200:
	print(f'응답 실패 :{url}, status : {status_code}')
	exit(1)

　하지만 모니터링을 해야 하는 URL이 1개에서 여러 개로 늘어난다면 어떻게 될까? 단순하게 작성한 Script를 아래처럼 약간 수정하면 되긴 하지만 URL마다 응답속도가 다를 경우 순차적으로 실행하다 보니 실행 속도는 느릴 수밖에 없다.

import requests
urls = [
	"http://모니터링url-1",
	"http://모니터링url-2",
	"http://모니터링url-3"
]

for url in urls:
	status_code = requests.get(url).status_code
	if status_code != 200:
		print(f'응답 실패 :{url}, status : {status_code}')
		exit(1)

 　이러한 경우, 빠른 속도를 보장하기 위해서는 병렬로 실행을 해야 한다는 건 누구나 다 알지만 그렇다고 Thread를 사용하기엔 벌써부터 덜컥 부담이 된다. 그렇다고 Job을 URL 개수만큼 늘리기에는 배보다 배꼽이 더 커버리고… 그러다 발견한 기능이 바로 Jenkins Pipeline!

　이번 포스팅에서는 Jenkins Job을 동시에 여러 번 사용해야 하는 경우를 Pipeline을 통해서 개선한 내용에 대하여 공유해보려 한다. Jenkins Pipeline에 대해 들어만 봤는데 이번에 실제로 사용해보니 생각보다 쉽게 개선할 수 있었고 옵션들을 상황에 맞게 조합을 잘 한다면 상당히 활용성이 높아 보이는 기능인 것 같다.

기존상황

　테스트를 위해 임의로 느린 응답을 생성하도록 URL을 구성하고 위에서 이야기했던 것처럼 Job 하나에 아주 심플하게 Python script를 작성하고 실행해보도록 하자. 임의로 느린 응답은 http://slowwly.robertomurray.co.uk/ 에서 제공하는 기능을 활용하였다.

import requests
urls = [
	"http://slowwly.robertomurray.co.uk/delay/0/url/https://www.naver.com/",
	"http://slowwly.robertomurray.co.uk/delay/100/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/200/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/500/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/1000/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/2000/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/5000/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/10000/url/https://www.naver.com/",
    "http://slowwly.robertomurray.co.uk/delay/20000/url/https://www.naver.com/"
]

for url in urls:
	status_code = requests.get(url).status_code
	if status_code != 200:
		print(f'응답 실패 :{url}, status : {status_code}')
		exit(1)
	print(f'응답성공 : {url}')

그래서 실행해보면 50초가 소요되었다. 자, 이제 개선을 해보자!

개선을 해보자

　전체적인 개선의 흐름은 하나의 Job에 모니터링하고자 하는 url을 파라미터로 받아서 처리할 수 있도록 설정하고, 이를 Jenkins Pipeline 을 통해 여러 URL을 동시에 모니터링하게 구성하는 것이다. 그러면 두 개의 Job(파라미터로 받아 모니터링하는 Job, Jenkins Pipeline Job) 만으로 보다 빠르고 효율적인 구성을 할 수 있을 것으로 상상을 하고.

Job을 범용적으로 (Jenkins paramters 활용)

　위에서 샘플로 작성하였던 Python script는 url 이 늘어날수록 Job 안에 script를 수정해야 한다. 그렇게 해도 무방하지만 이번 개선의 목표는 하나의 Job을 Pipeline 이 병렬로 컨트롤하도록 설정해야 했기 때문에 Jenkins Job에 파라미터를 받을 수 있도록 아래처럼 Jenkins Job 설정에 파라미터를 설정하고 Python script 또한 수정해 주자.

import requests, os
url = os.environ['url']
status_code = requests.get(url).status_code

if status_code != 200:
  print(f'응답 실패 :{url}, status : {status_code}')
  exit(1)
  
print(f'응답성공 : {url}')

병렬 실행을 위한 Jenkins 설정

　Jenkins Job 을 생성하면 기본적으로 Job마다의 대기열(Queue)이 있어 Job이 실행 중이라면 시작된 시간 순서대로 기다렸다가 앞선 Job이 종료가 되면 이어서 실행되는 구조이다. 하지만 우리는 Job을 병렬로 실행해야 했기에 Job 설정 중 필요한 경우 concurrent 빌드 실행 옵션을 켜줘서 기다리지 않고 병렬로 실행될 수 있도록 해준다.

　또한 Jenkins Job 자체는 병렬로 실행되도록 설정되었다 해도 기본적으로 Jenkins 자체의 대기열은 한정되어 있기 때문에 적당히 늘려줘서 여러 개의 Job이 대기 열 없이 동시에 실행될 수 있도록 해준다.

Jenkins Pipeline

　Job 을 Pipeline으로 만들고 Pipeline scirpt를 작성하는데 눈여겨봐야 할 옵션들을 짚고 넘어가고자 한다.

　웹서비스 개발자라면 나만의 블로그쯤은 있어야지 하며 기술 블로그를 시작한 지도 어느덧 4년이 되었다. 처음엔 그저 새로 알게 된 기술이나 삽질하며 경험한 것들 중에 핵심만을 적어놓는 수준이었다. (지금 다시 보면 뭔가 오글거리는 건 기분 탓이겠지…) 그렇게 계속 글을 써오면서 글쓰기라는 것에 관심을 갖게 되고 내 글이 누군가에게 도움이 될 거라는 기대에 조금이라도 글을 잘 써보고자 단순 기록 용이 아닌 하나의 ‘글’을 쓰려고 노력해 온 것 같다.

　일주일에 한 개는 써야지. 한 달에 한 개는 써야지. 하며 자꾸 나 자신과의 타협을 하다가 최근에는 회사에서 운영하는 서비스 개편 때문에 정신없이 바쁘다는 핑계로 ‘블로그’에 ‘ㅂ’자도 생각하지 못하게 된다. 무엇이 문제일까?라는 생각은 결국 내 기술 블로그도 회사 서비스처럼 ‘개편’을 해보자는 생각으로 도달하게 되었고 간단할 것만 같았던 기술 블로그 개편 작업은 꽤 오랫동안 + 다양한 삽질들로 작업을 하게 된다.

　이번 포스팅에서는 기술 블로그를 개편하며 겪었던 내용들에 대해 정리해보고자 한다. 기존에 기술 블로그를 운영하시는 분들이나 이번에 새롭게 시작하시는 분들께 도움이 될 거라 기대한다. 더불어 서비스 ‘출시’ 가 아닌 개편’이라는 과정 속에서 느끼게 되었던 인사이트도 간략하게 작성해볼까 한다.

기술블로그 플랫폼 선택

　처음 블로그를 쓰기 시작했을 때 포털서비스의 글쓰기 플랫폼을 사용하지 않은 이유는 단 하나다. ‘글쓰기’ 뿐만 아니라 개발자이기에 웹사이트(블로그)를 내 입맛에 맞게 커스터마이징 하기 위해서. 그 이유로 hexo 라는 프레임워크에 github의 호스팅을 사용하여 운영을 해왔다. 그렇게 블로그를 운영해오면서 느꼈던 불편했던 부분들과 개편을 하며 기대하는 부분들을 정리하면 아래와 같다.

• 테마(UI)가 이뻐야 하고 기능들이 많으면 좋겠다.
• 기술 블로그인 만큼 코드가 많이 삽입되니 코드 표현 또한 이뻐야 한다.
• 테마 또는 프레임워크의 커뮤니티가 활발해야 한다.
• 페이지 생성 또는 만들어진 웹페이지의 성능이 좋아야 한다.
• 글을 작성하고 배포하는 과정이 심플하고 깔끔해야 한다. 

　위와 같은 이유를 기반으로 검색을 해보다 SSG(쓱 쇼핑몰 아님, Static site generators)를 깔끔하게 정리해 놓은 사이트를 발견한다. 정말 다양한 플랫폼들을 살펴보며 필자에게 맞는 게 어떤 건지 고민하다 결국 hugo 를 선택하게 된다. hugo를 선택한 이유는 go라는 언어를 사용한다는 것과 (간접적으로라도 다른 언어를 경험해보고 싶어서 + go 언어가 빠르다는 소리를 어디선가 들어서) 테마들이 너무 다양했기 때문이다.

　결국 hugo에 hugo-ranking-trend라는 사이트에서 상위에 랭크가 되어있고 기술 블로그 성격에 적합할 것 같은 LoveIt이라는 테마를 사용하기로 결정하였다. 자 그럼 시작해볼까?!

hugo 는 어떻게 쓰는거야?

　대부분의 오픈소스는 hello world 혹은 quick start 같이 처음 접하는 사람들을 위한 도큐먼트가 있기 마련. hugo도 마찬가지로 quick-start가 있었고 이를 천천히 따라 하면 생각보다 쉽게 초기 세팅을 할 수 있었… 을꺼라 기대했지만 약간 초기 설정 과정이 어려워서 남겨 두고자 한다.

참고로 필자는 윈도 10 환경에서 구성하였다. mac이라면 더 쉽게 설정할 수 있는 것 같은데 이 부분은 OS의 차이에서 생겨나는 어쩔 수 없는 약간의 장벽이라 생각한다. 이쁜 테마와 새로운 환경을 사용할 수 있다는 기대감으로 꾹 참아본다.

기본설정

　git이 설치되어 있다는 가정하에 우선 hugo는 go 언어기반으로 돌아가기에 우선 go를 설치해야 한다. 다운로드페이지에서 환경에 맞는 설치 파일을 다운로드하고 설치를 해준다. 다음으로 패키지 관리자인 chocolatey 또한 설치가 필요하다. 공식 홈페이지페이지에서 나와있는 순서대로 진행하면 설치 완료. 필자는 여기서 진행이 잘 안됐었는데, ‘관리자 권한’으로 PowerShell 을 실행시켜야지만 성공을 할 수 있었다.

　위 설정이 완료되었으면 드디어 hugo를 설치해 주고 초기화를 해준 뒤 샘플로 글 하나를 만들고 서버를 띄우면 끝.

　캐릭터를 육성하며 게임하는 경우를 생각해 보자. 더 좋은 아이템을 얻거나 퀘스트를 달성하기 위해 당신은 다양한 방법을 통해 캐릭터를 성장시킨다. 사냥을 하다 체력이 떨어지게 되면 물약을 먹고, 캐릭터의 능력 중 부족한 부분이 있으면 훈련을 더 하거나 그에 맞는 아이템을 장착하게 된다. 이렇게 캐릭터의 ‘상태’를 적절한 UI를 통해 사용자에게 알려주기 때문에 ‘확인’이 가능하고 ‘대응’이 가능하게 된다.

　우리가 만드는 애플리케이션 또한 위에서 이야기 한 게임상의 캐릭터가 아닐까 싶다. 복잡한 스펙을 다양한 테스트 케이스를 만들며 로직 동작에는 이상이 없음을 확인했다면 그걸로 만족할 수 있을까? 개발자의 ‘레벨’은 이 부분에서 차이가 난다고 생각한다. 운영환경에 출시한 애플리케이션에 에러가 나는지, 트래픽이 얼마나 들어오고 있고 트래픽의 유형은 또 어떠한지, 요청에 대한 응답속도는 어떻고 서버의 시스템 지표에는 문제가 없는지 등등. 애플리케이션의 유형에 따라 다양하겠지만 적절한 로그를 이용하여 애플리케이션의 ‘상태’를 확인하고 문제가 있다면 ‘대응’하는 게 꼭 필요하다고 생각한다.

　이번 포스팅에서는 크게 로깅과 모니터링에 대해 알아보고자 한다. 이를 통해 애플리케이션의 ‘개발’에만 집중하고 있던 관점을 보다 더 높은 곳에서 바라보며 애플리케이션의 ‘운영’ 측면에서도 고민해 보는 기회가 되었으면 한다.

필자는 서버 개발자이다 보니 글의 내용이 다소 서버 개발자의 시선에서 작성하게 되었다. 하지만 ‘개발자’라면 유형만 다르지 대부분 비슷하기 때문에 크게 다르지 않다고 생각한다.

로그는 어떤걸, 어떻게 남겨야 할까?

　로그가 왜 필요한지에 대한 내용은 다루지 않겠다. (굳이 말하지 않아도 그만큼 중요하다는 표현이 더 어울릴 수도 있겠다.) 그렇다면 우선 어떤 로그를 남겨야 할까?

　아직까지도 기억에 남아있는 예전 조직 장님과의 대화. 일단 로그는 최대한 많이 (과하게) 남겨야 한다고 생각한다. 그다음 불필요한 로그들은 제거하거나 레벨을 낮추는 등 상황에 맞도록 커스터마이징이 필요하다. 경험을 해보면 알겠지만 운영환경에 애플리케이션을 배포하고 서비스를 운영하다 보면 개발 환경에서 만나기 어렵거나 경험해보지 못한 상황이 발생하곤 한다. 이럴 때 상황에 맞는 로그들이 있다면 미리 남겨둔 로그를 통해 더 효과적으로 상황을 파악할 수 있다. 트래픽의 정보(request url, parameter, UA, remote ip 등)를 남겨서 외부에서 호출하는 형태를 분석하는데 활용할 수도 있고, 애플리케이션에서 외부로 호출을 하고 난 뒤에 받는 응답에 대해서 로그를 남겨두면 외부 통신의 오류를 파악하는 데 도움이 될 수 있다. 어떤 로그를 남겨야 하는가에 대한 고민은 운영하는 애플리케이션이 어떤 행동을 하는가에 관점을 두고 고민해보면 좀 더 쉽게 찾을 수 있을 것이라 생각한다.

　로그를 남기는 방법 또한 다양하다. 시스템 로컬에 파일로 남기거나 특정 로그 서버를 설정하여 여러 대의 서버 로그를 한곳에서 볼 수도 있다. 다만 로그를 ‘남기는’ 것 또한 하나의 비용에 포함되기 때문에 애플리케이션의 기능에 최대한 영향이 가지 않도록 최대한 빠른 시간 내에 처리가 되도록 해야 한다. (혹은 비동기로 남기거나 등)

　로그를 남기는 이유 중 가장 큰 이유는 ‘나중에 보기 위해서’이다. 그만큼 한번 로그를 남길 때에도 보기 좋게 남겨야 한다. 예컨대, 아래에 적어놓은 로그 방식의 경우 작은 차이지만 나중에 볼 때 꽤 큰 차이를 유발한다. 

• 안좋은 예

try {
	...
} catch (Exception e){
	log.Error(e); // 어떤 상황이지..?
}

• 보다 조금 더 좋은 예

try {
	...
} catch (Exception e){
	log.Error("url : " + url + ", parameter : " + parameter + ", remote ip : " + remoteIp, e); // 로그는 가급적 자세하게 !
}

로그가 가져다 주는 또 다른 세상

　로그는 또 다른 데이터가 될 수 있다. 글 목록을 보여주는 웹페이지가 있다고 가정해보자. 이때 사용자들이 어떤 글을 더 많이 읽는지 ‘클릭 지표’에 대한 로그를 남겨 둔다면 ‘인기글’ 같은 또 다른 웹 페이지가 나올 수 있을 것 같다. 만약 그 페이지가 회원만 읽을 수 있는 페이지라면 ‘20대 남성이 월요일 오후에 많이 읽는 글’ 같이 회원의 정보를 조합하여 새로운 데이터를 만들 수 있게 된다. 이러한 데이터들은 보다 더 좋은 서비스를 할 수 있게 도와줄 수 있는 밑거름이 되고 그 바탕은 로그라는 걸 명심하자.

　git 은 분산 버전 관리 시스템 중 가장 잘 알려져 있다고 해도 과언이 아닐 정도로 대부분의 시스템에서 사용되고 있는 것 같다. 이를 웹서비스에서 보다 편하게 사용할 수 있도록 한 시스템이 Github. Github 을 사용하는 이유 중에 가장 큰 이유를 하나만 이야기해보자면 바로 온라인상에서 코드 리뷰를 할 수 있는 pullRequest라는 기능 때문이 아닐까 조심스럽게 생각을 해본다.

　pullRequest는 work branch에서 작업한 내용을 base branch로 merge 전 꼭 코드 리뷰가 아니더라도 작업한 내용에 대해서 다양한 검사를 자동화할 수 있는 강력한 기능들이 많다. 이러한 자동화는 CI(지속적 통합) 관점에서 매우 중요한데 코드에 대해 체크해야 할 부분들(빌드, 테스트, 정적 분석 등)을 “알아서” 해준다면 작업자는 오롯이 비즈니스 로직 개발에 대해서만 신경 쓸 수 있으니 생산성 절약 측면에서 엄청난 효과를 볼 수 있다.

이번 포스팅에서는 그중에서도 아주 간단한 설정만으로 work branch의 빌드 상태를 검사해 볼 수 있는 Jenkins의 Github Pull Request Builder를 설치 및 활용해 보고자 한다.

사실 최근 팀에서 CI 서버를 이전해야 했었다. 머릿속에서는 어떻게 하면 되겠지 싶었지만 막상 해보려니 Jenkins 버전업도 되었고 뭐부터 해야 할지 허둥대는 필자가 부끄러웠다. 이참에 정리를 해보며 다시 한번 리마인드 하는 시간을 가져보고자 한다. (이래서 기억보다 기록이 중요하다.)

준비물

　전체적인 흐름은 아래 그림처럼 흘러가기 때문에 당연히 서버에 Jenkins 가 설치되어 있어야 한다. Jenkins 설치는 필자의 포스팅(Jenkins 설치 치트키)를 참고해 보는 것도 좋을 것 같다.

　참고로 필자는 GitHub Enterprise 버전에서 사용했는데 일반 Github에서도 동일한 방법으로 사용 가능하다.

Github과 Jenkins의 연동을 위한 2가지 설정

　Github 과 Jenkins 가 통신이 되도록 설정해 줘야 한다. 그래야 Github의 코드를 받아서 Jenkins 가 빌드를 하고 그 빌드 결과를 다시 Github에 리포트가 가능해지기 때문이다. 먼저 첫 번째로 ssh 설정으로 Github의 코드를 가져오도록 ssh 설정을 해두자. ssh 설정하는 방법은 필자의 포스팅(Github과 Jenkins 연동하기)편을 확인해보면 될 것 같다.

　그다음으로 아래에서 이야기할 GitHub Pull Request Builder라는 Jenkins plugin 이 빌드가 끝난 뒤에 결과를 리포팅 해줄 수 있는 인증 토큰을 발급받아두자. Github > Settings > Developer settings > Personal access tokens 화면에서 키를 생성하고 만들어진 키를 저장해 둔다. (이 키는 보안에 유의해야 하고, 화면 경고(?)에서도 볼 수 있듯이 키는 생성 시 한 번밖에 볼 수 없기 때문에 미리 저장해 둬야 한다.)

Jenkins 설정

　Jenkins > 관리 > pluginManager에 들어가 GitHub Pull Request Builder를 검색 후 설치해 준다. 그러고 나서 Jenkins > 관리 > 환경설정에 들어가 보면 아래와 같이 GitHub Pull Request Builder 항목이 생긴 것을 확인할 수 있고 위에서 설정한 인증토큰을 아래처럼 등록 후 저장을 한다.

　Jenkins job을 하나 만들고 pullRequest 가 발생했을 때 자동으로 실행될 수 있도록 설정을 해준다. 먼저 General 탭에 Github project에 Github url 을 적어주고

　소스 코드 관리 탭에서 ssh 주소를 적고 위에서 미리 설정한 ssh 키로 credentials 값을 넣어준다. 전에도 이야기했지만 이 부분에서 오류가 발생하면 빨간색 글씨로 오류 내용이 나오고 아래 화면처럼 오류가 없다면 아무것도 안 나온다. Refspec 에 +refs/pull/*:refs/remotes/origin/pr/* 라고 적어주고 브랜치 설정은 파라미터로 받아와서 pullRequest를 발생시킨 브랜치를 빌드 할 수 있도록 ${sha1} 라고 적어주자.