Java Agent Plugin Guide - PDF Free Download

Java Agent Plugin Guide Whatap Support Version 1.0.2

Table of Contents Java Agent Plugin 가이드..................................................................................... 1 1. 에이전트옵션.......................................................................................... 2 1.1. hook_trace_helper_end_patterns....................................................................... 2 1.2. hook_trace_helper_start_patterns....................................................................... 2 1.3. hook_trace_helper_patterns........................................................................... 2 1.4. custom_pool_classes................................................................................ 2 1.5. 설정예........................................................................................... 2 2. Plugin 코드작성예..................................................................................... 4 2.1. 설정한메소드시작시간을프로파일에기록하는예............................................................ 4 2.2. 설정한메소드종료시간과수행시간을프로파일에기록하는예................................................... 5 3. Plugin API............................................................................................ 7 3.1. 데몬및배치....................................................................................... 9 3.2. HTTP 서비스....................................................................................... 9 3.3. HTTP Outbound................................................................................... 10 3.4. 특정된메소드..................................................................................... 11 3.5. 사용자정의 Pool................................................................................... 11 4. Plugin 적용사례...................................................................................... 12 4.1. ElasticSearch 엔진의검색요청모니터링................................................................. 12

Preface Java Agent Plugin 가이드 제목 : Java Agent Plugin Guide 작성자 : Whatap Support 이메일 : support@whatap.io 날짜 : 2019-05-16 버전 : 1.0.2 설명 : Java Agent Plugin 적용방법에대해설명합니다. 와탭에서제공하는 Plugin 을활용해프로파일정보내에부가적인정보를추가하거나, 메소드수행전 / 후로원하는코드를주입하는것과같은 다양한일을할수있습니다. Copyright c 2019 WhaTap Labs Inc. All rights reserved. 1

1.1. hook_trace_helper_end_patterns Chapter 1. 에이전트옵션 에이전트플러그인은메소드시작 / 종료부분에삽입되어실행됩니다. 플러그인을적용할위치 ( 클래스, 메소드명 ) 를지정하는옵션은다음과 같습니다. 1.1. hook_trace_helper_end_patterns 메소드종료부분에프로파일플러그인을삽입할포인트 ( 클래스및메소드명 ) 를지정합니다. 플러그인코드는 $WHATAP_HOME/plugin/TraceHelperEnd.x 파일에작성합니다. 1.2. hook_trace_helper_start_patterns default: 메소드시작부분에프로파일플러그인을삽일할포인트 ( 클래스및메소드명 ) 를지정합니다. 플러그인코드는 $WHATAP_HOME/plugin/TraceHelperStart.x 파일에작성합니다. 1.3. hook_trace_helper_patterns 메소드시작 / 종료양쪽에프로파일플러그인을삽입할포인트 ( 클래스및메소드명 ) 를지정합니다. 플러그인코드는 $WHATAP_HOME/plugin/TraceHelperStart.x, $WHATAP_HOME/plugin/TraceHelperEnd.x 각각작성합니다. 1.4. custom_pool_classes 사용자정의 Pool 을모니터링하기위해 Pool 사용량정보를가진클래스를지정합니다. 플러그인코드는 $WHATAP_HOME/plugin/CustomPool.x 에작성합니다. 1.5. 설정예 여러개의클래스를지정하는경우, 로구분합니다. 패키지명의문자열일부 / 전부를 * 로치환할수있습니다. 패키지와메소드 Full Name 을지정하는경우 whatap.bytecode.instrument.plugintesta.testa, whatap.bytecode.instrument.plugintestb.testb 패키지명과메소드일부를 * 로치환한경우 *PluginTestA.testA, whatap.bytecode.instrument.plugintestb.* *.testa, *PluginTestB.testB 전체를대상으로하는경우 *.* Custom Pool 은식별자 @ 패키지명형태로지정합니다. Custom Pool 을지정하는경우 whatap_plugin_guide@com.ibm.ws.connectionpool.monitor.connectionpoolstats 1 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 2

2.1. 설정한메소드시작시간을프로파일에기록하는예 Chapter 2. Plugin 코드작성예 plugin 코드작성예입니다. 대부분의경우 Object 를반환하므로명시적 type casting 처리가필요합니다. 2.1. 설정한메소드시작시간을프로파일에기록하는예 에이전트 hook_trace_helper_patterns 옵션에적용할메소드를정의합니다. $WHATAP_HOME/whatap.conf hook_trace_helper_patterns=org.apache.catalina.connector.requestfacade.* TraceHelperStart.x 에 Plugin 코드를작성합니다. $WHATAP_HOME/plugin/TraceHelperStart.x String prefix = $point.class1 + "." + $point.method; 1 $ctx.setattribute(prefix + "st", new Long(System.currentTimeMillis())); 2 $ctx.profile(prefix + " Start", new java.util.date().tostring()); 3 1 String prefix 에클래스명, 메소드명을대입합니다. 2 와탭프로파일속성명 prefix + "st" 로현재시간을설정합니다. 3 프로파일정보에현재시간을추가합니다. 프로파일내역에메소드시작시간이표시됩니다. Copyright c 2019 WhaTap Labs Inc. All rights reserved. 4

2.2. 설정한메소드종료시간과수행시간을프로파일에기록하는예 Figure 1. 시작시간기록된프로파일내역 2.2. 설정한메소드종료시간과수행시간을프로파일에기록하는예 에이전트 hook_trace_helper_patterns 옵션에적용할메소드를정의합니다. $WHATAP_HOME/whatap.conf hook_trace_helper_patterns=org.apache.catalina.connector.requestfacade.* TraceHelperEnd.x 에 Plugin 코드를작성합니다. $WHATAP_HOME/plugin/TraceHelperEnd.x String prefix = $point.class1 + "." + $point.method; long st = ((Long) $ctx.getattribute(prefix + "st")).longvalue(); 1 long gap = System.currentTimeMillis() - st; StringBuilder sb = new StringBuilder(); sb.append(new java.util.date().tostring() + " (Gap:" + gap + " milliseconds)"); $ctx.profile(prefix + " End", sb.tostring()); 2 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 5

2.2. 설정한메소드종료시간과수행시간을프로파일에기록하는예 1 TraceHelperStart.x 에서추가한프로파일속성을가져옵니다. 2 프로파일정보에시작시간과의현재시간과의 Gap( 수행시간 ) 을추가합니다. 프로파일내역에메소드종료시간과수행시간이표시됩니다. Figure 2. 종료 / 수행시간까지기록된프로파일내역 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 6

Chapter 3. Plugin API Chapter 3. Plugin API Plugin API 는공통항목인 $ctx, $point 와 $pack, $req, $res 로구분됩니다. 트랜잭션시작 / 종료시, HTTPC 구간, 특정메소드실행구간등에적용가능합니다. Table 1. 공통속성 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 7

$point String class1 클래스명 3.1. 데몬및배치 String method Object this1 메소드명 Hooking 대상클래스 / 메소드 Object[] args 인자 와탭패키지 파라미터 메소드 / 변수 설명 Object return 리턴 void log(object c) void println(object c) Object field(object o, String field) Object method(object o, String method) Object method(object o, String method, String param) String tostring(object o) String tostring(object o, String def) int syshash(object o) int syshash(hookargs hook, int x) int syshash(hookargs hook) int cint(object o) float cfloat(object o) String cstring(object o) long clong(object o) double cdouble(object o) String desc(object o) String tojson(object o) void shell(final String cmd, final String env) Logger 를통한 Logging System.out.println() 을통한출력 Field 값반환 Invoke 메소드 Invoke 메소드 Object 를 tosting() 반환 Object 를 tosting() 반환, null 인경우 def 반환 hash 값반환 x 번째 argument의 hash 값반환 argument의 hash 값반환 int 로반환 float 으로반환 String 으로반환 long 으로반환 double 로반환 Class signature 반환 json 으로반환 shell 실행 3.1. 데몬및배치 데몬, 배치와같은어플리케이션을모니터링할때시작점으로설정한메소드에적용하는 API 입니다. 서비스시작부분에적용하는경우 $WHATAP_HOME/plugin/AppServiceStart.x, 서비스종료부분이라면 $WHATAP_HOME/plugin/AppServiceEnd.x 라는파일명으로코드를작성합니다. Table 2. 일반서비스 ( 데몬및배치 ) 와탭패키지파라미터메소드 / 변수설명 AppServiceS tart.x AppServiceS tart.process $ctx $point 공통속성참조 공통속성참조 AppServiceE nd.x AppServiceE nd.process $ctx 공통속성참조 3.2. HTTP 서비스 javax.servlet.http.httpservlet 을사용하는일반적인웹어플리케이션에적용할수있는 API 입니다. 서비스시작부분에적용하는경우 $WHATAP_HOME/plugin/HttpServiceStart.x, 서비스종료부분이라면 $WHATAP_HOME/plugin/HttpServiceEnd.x 라는파일명으로코드를작성합니다. Table 3. HTTP 서비스 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 9

3.3. HTTP Outbound 와탭패키지파라미터메소드 / 변수설명 HttpService Start.x/ HttpService End.x HttpService Start.proces s/ HttpService End.process $ctx 공통속성참조 $req String getcookie(string key) Cookie 값반환 String getrequesturi() RequestURI 반환 String getremoteaddr() String getmethod() String getquerystring() String getparameter(string key) Object getattribute(string key) String getheader(string key) Enumeration getparameternames() Enumeration getheadernames() WrSession getsession() Set getsessionnames() Object getsessionattribute(string key) boolean isok() Throwable error() RemoteAddr 반환 HTTP Method 반환 HTTP QueryString 반환 Parameter 값반환 Attribute 값반환 Header 값반환 getparameternames 반환 getheadernames 반환 Session Wrapper 반환 getsessionnames 반환 getsessionattribute 반환 Plugin 상태반환 Error 반환 $res String getcontenttype() ContentType 반환 String getcharacterencoding() boolean isok() Throwable error() CharacterEncoding 반환 Plugin 상태반환 Error 반환 3.3. HTTP Outbound HttpClient 와같은라이브러를사용하여 HTTP Outbound Call 수행할때적용할수있는 API 입니다. 서비스시작부분에적용하는경우 $WHATAP_HOME/plugin/HttpCallStart.x, 서비스종료부분이라면 $WHATAP_HOME/plugin/HttpCallEnd.x 라는파일명으로코드를작성합니다. Table 4. HTTP Outbound 와탭패키지파라미터메소드 / 변수설명 HttpCallStar t.x HttpCallStar t.process $ctx 공통속성참조 $req String url() URL 반환 String host() int port() boolean isok() Throwable error() Hostname 반환 Port 반환 Plugin 상태반환 Error 반환 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 10

3.4. 특정된메소드 와탭패키지파라미터메소드 / 변수설명 HttpCallEnd. x HttpCallEnd. process $ctx 공통속성참조 $res String getcontenttype() ContentType 반환 String getcharacterencoding() boolean isok() Throwable error() CharacterEncoding 반환 Plugin 상태반환 Error 반환 3.4. 특정된메소드 와탭에이전트옵션 (hook_trace_helper_*) 을통해지정한메소드에대해적용하는 API 입니다. Table 5. 지정한메소드구간 와탭패키지파라미터메소드 / 변수설명 TraceHelper Start.x TraceHelper Start.proces s $ctx $point 공통속성참조공통속성참조 TraceHelper End.x TraceHelper End.process $ctx $point 공통속성참조공통속성참조 3.5. 사용자정의 Pool 사용자정의 Pool 을모니터링하기위한 API 입니다. Pool 사용량정보를가진메소드를지정하면와탭에서모니터링하고통계정보를확인할수있습니다. 사례와같이사용됩니다. Table 6. Custom Pool 와탭패키지파라미터메소드 / 변수설명 CustomPool. x CustomPool. process $id $pool custom_pool_classes 에설정한 id 값 custom_pool_classes 에설정한 class $result int active(object o) Active Pool Count 지정 int idle(object o) Idle Pool Count 지정 Copyright c 2019 WhaTap Labs Inc. All rights reserved. 11

4.1. ElasticSearch 엔진의검색요청모니터링 Chapter 4. Plugin 적용사례 실제 Plugin 적용사례입니다. 4.1. ElasticSearch 엔진의검색요청모니터링 ElasticSearch 엔진 ( 이하 ES) 는서블릿엔진이아니기때문에비정형모니터링을해야합니다. 타제품이지표중심의모니터링을한다면와탭의 Plugin 을활용하면 ES 의요청, 처리시간그리고검색키워드를프로파일링할수있습니다. whatap.conf hook_service_patterns=org.elasticsearch.search.searchservice.executequeryphase 1 hook_trace_helper_start_patterns=org.elasticsearch.search.query.queryphase.execute 2 1 트랜잭션 EndPoint 로 org.elasticsearch.search.searchservice.executequeryphase 를설정합니다. 2 hook_trace_helper_start_patterns 에등록된메소드가실행될때마다 TraceHelperStart.x 내의코드가실행됩니다. ${WHATAP_HOME}/plugin/TraceHelperStart.x if ($ctx.inner()==null){ return; } try { String tclass = "org.elasticsearch.search.query.queryphase"; String tmethod = "execute"; if (tclass.equals($point.class1) && tmethod.equals($point.method)) { // 첫번째 argument 의 query 메소드호출결과를 String query 에저장 String query = " " + method($point.args[0],"query"); 1 // String query를프로파일정보로출력 $ctx.profile(query); } } catch(exception e) { $ctx.profile(e.tostring()); } 1 org.elasticsearch.search.query.queryphase.execute(searchcontext searchcontext) 입니다. 즉, SearchContext.query() 메소드를 invoke 한결과를 String query 에저장합니다. Copyright c 2019 WhaTap Labs Inc. All rights reserved. 12