You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by ha...@apache.org on 2021/10/15 11:49:26 UTC
[skywalking-swck] branch master updated: add JavaAgent doc and
update demo (#35)
This is an automated email from the ASF dual-hosted git repository.
hanahmily pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking-swck.git
The following commit(s) were added to refs/heads/master by this push:
new f35457c add JavaAgent doc and update demo (#35)
f35457c is described below
commit f35457cdba6dfde9099525275d9abb9fd915ee7b
Author: dashanji <71...@users.noreply.github.com>
AuthorDate: Fri Oct 15 19:49:22 2021 +0800
add JavaAgent doc and update demo (#35)
---
README.md | 11 ++
docs/examples/java-agent-injector-usage.md | 296 +++++++++++++++++++++++------
docs/java-agent-injector.md | 4 +
docs/javaagent.md | 82 ++++++++
4 files changed, 330 insertions(+), 63 deletions(-)
diff --git a/README.md b/README.md
index 01efe56..fa9fb11 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ SWCK is a platform for the SkyWalking user, provisions, upgrades, maintains SkyW
1. Operator: Provision and maintain SkyWalking backend components.
1. Custom Metrics Adapter: Provides custom metrics come from SkyWalking OAP cluster for autoscaling by Kubernetes HPA
+ 1. Java Agent Injector: Inject the java agent into the application pod natively.
# Quick Start
@@ -35,6 +36,7 @@ There are some instant examples to represent the functions or features of the Op
- [Deploy OAP server and UI with default settings](./docs/examples/default-backend.md)
- [Fetch metrics from the Istio control plane(istiod)](./docs/examples/istio-controlplane.md)
+ - [Inject the java agent into the application pod](./docs/examples/java-agent-injector-usage.md)
## Custom Metrics Adapter
@@ -47,6 +49,15 @@ There are some instant examples to represent the functions or features of the Op
For more details, please read [Custom metrics adapter](docs/custom-metrics-adapter.md)
+## Java Agent Injector
+
+* Inject the java agent into the application pod.
+* Use the default agent configuration.
+* Use annotations to overlay sidecar configuration and agent configuration.
+* Get the final injected agent's configuration.
+
+For more details, please read [Java agent injector](docs/java-agent-injector.md)
+
# Contributing
For developers who want to contribute to this project, see [Contribution Guide](CONTRIBUTING.md)
diff --git a/docs/examples/java-agent-injector-usage.md b/docs/examples/java-agent-injector-usage.md
index ab5ee50..b045989 100644
--- a/docs/examples/java-agent-injector-usage.md
+++ b/docs/examples/java-agent-injector-usage.md
@@ -14,23 +14,29 @@ At first, set the injection label in your namespace as below.
kubectl label namespace default(your namespace) swck-injection=enabled
```
-Then add `swck-java-agent-injected: "true"` in the labels of yaml file as below.
+Then add `swck-java-agent-injected: "true"` in the labels of the yaml file as below.
```
-apiVersion: v1
-kind: Pod
+apiVersion: apps/v1
+kind: Deployment
metadata:
- name: inject-demo
- labels:
- swck-java-agent-injected: "true"
- app: demo
+ name: demo1
namespace: default
spec:
- containers:
- - name: demo
- image: dashanji/swck-spring-demo:v0.0.3
- command: ["java"]
- args: ["-jar","$(AGENT_OPTS)","-jar","/app.jar"]
+ selector:
+ matchLabels:
+ app: demo1
+ template:
+ metadata:
+ labels:
+ swck-java-agent-injected: "true"
+ app: demo1
+ spec:
+ containers:
+ - name: demo1
+ image: dashanji/swck-spring-demo:v0.0.3
+ command: ["java"]
+ args: ["-jar","$(AGENT_OPTS)","-jar","/app.jar"]
```
@@ -50,7 +56,7 @@ spec:
- name: AGENT_OPTS
value: -javaagent:/sky/agent/skywalking-agent.jar
image: dashanji/swck-spring-demo:v0.0.3
- name: demo
+ name: demo1
- mountPath: /sky/agent
name: sky-agent
- mountPath: /sky/agent/config
@@ -80,6 +86,52 @@ NAME DATA AGE
skywalking-swck-java-agent-configmap 1 61s
```
+Then you can get the final agent configuration and the pod as below.
+
+```shell
+$ kubectl get javaagent
+NAME PODSELECTOR SERVICENAME BACKENDSERVICE
+app-demo1-javaagent app=demo1 Your_ApplicationName 127.0.0.1:11800
+$ kubectl get pod -l app=demo1(the podSelector)
+NAME READY STATUS RESTARTS AGE
+demo1-8554b96b4c-6czv7 1/1 Running 0 85s
+```
+
+Get the javaagent's yaml for more datails.
+
+```shell
+$ kubectl get javaagent app-demo1-javaagent -oyaml
+apiVersion: operator.skywalking.apache.org/v1alpha1
+kind: JavaAgent
+metadata:
+ creationTimestamp: "2021-10-15T04:52:46Z"
+ generation: 1
+ name: app-demo1-javaagent
+ namespace: default
+ ownerReferences:
+ - apiVersion: apps/v1
+ blockOwnerDeletion: true
+ controller: true
+ kind: ReplicaSet
+ name: demo1-8554b96b4c
+ uid: f3d71b5c-1e26-401a-8d0d-055d1e89bc64
+ resourceVersion: "455104"
+ selfLink: /apis/operator.skywalking.apache.org/v1alpha1/namespaces/default/javaagents/app-demo1-javaagent
+ uid: 2bf828d6-4f83-4c7d-9356-83066ae334d3
+spec:
+ agentConfiguration:
+ agent.service_name: Your_ApplicationName
+ collector.backend_service: 127.0.0.1:11800
+ backendService: 127.0.0.1:11800
+ podSelector: app=demo1
+ serviceName: Your_ApplicationName
+status:
+ creationTime: "2021-10-15T04:52:46Z"
+ expectedInjectiedNum: 1
+ lastUpdateTime: "2021-10-15T04:52:49Z"
+ realInjectedNum: 1
+```
+
## Use annotation to override sidecar configuration
At first, set the injection label in your namespace as below.
@@ -91,29 +143,36 @@ kubectl label namespace default(your namespace) swck-injection=enabled
Then add `swck-java-agent-injected: "true"` in the labels of yaml file and add the [sidecar configuration](../java-agent-injector.md#configure-sidecar) to the annotations as below.
```
-apiVersion: v1
-kind: Pod
+apiVersion: apps/v1
+kind: Deployment
metadata:
- labels:
- swck-java-agent-injected: "true"
- annotations:
- sidecar.skywalking.apache.org/initcontainer.Name: "test-inject-agent"
- sidecar.skywalking.apache.org/initcontainer.Image: "apache/skywalking-java-agent:8.5.0-jdk8"
- sidecar.skywalking.apache.org/initcontainer.Command: "sh"
- sidecar.skywalking.apache.org/initcontainer.args.Option: "-c"
- sidecar.skywalking.apache.org/initcontainer.args.Command: "mkdir -p /skytest/agent && cp -r /skywalking/agent/* /skytest/agent"
- sidecar.skywalking.apache.org/sidecarVolumeMount.MountPath: "/skytest/agent"
- sidecar.skywalking.apache.org/configmapVolumeMount.MountPath: "/skytest/agent/config"
- sidecar.skywalking.apache.org/configmapVolume.ConfigMap.Name: "haha"
- sidecar.skywalking.apache.org/env.Value: "-javaagent:/skytest/agent/skywalking-agent.jar"
- name: inject2
+ name: demo2
namespace: default
spec:
- containers:
- - name: demo
- image: dashanji/swck-spring-demo:v0.0.3
- command: ["java"]
- args: ["-jar","$(AGENT_OPTS)","-jar","/app.jar"]
+ selector:
+ matchLabels:
+ app: demo2
+ template:
+ metadata:
+ labels:
+ swck-java-agent-injected: "true"
+ app: demo2
+ annotations:
+ sidecar.skywalking.apache.org/initcontainer.Name: "test-inject-agent"
+ sidecar.skywalking.apache.org/initcontainer.Image: "apache/skywalking-java-agent:8.5.0-jdk8"
+ sidecar.skywalking.apache.org/initcontainer.Command: "sh"
+ sidecar.skywalking.apache.org/initcontainer.args.Option: "-c"
+ sidecar.skywalking.apache.org/initcontainer.args.Command: "mkdir -p /skytest/agent && cp -r /skywalking/agent/* /skytest/agent"
+ sidecar.skywalking.apache.org/sidecarVolumeMount.MountPath: "/skytest/agent"
+ sidecar.skywalking.apache.org/configmapVolumeMount.MountPath: "/skytest/agent/config"
+ sidecar.skywalking.apache.org/configmapVolume.ConfigMap.Name: "newconfigmap"
+ sidecar.skywalking.apache.org/env.Value: "-javaagent:/skytest/agent/skywalking-agent.jar"
+ spec:
+ containers:
+ - name: demo2
+ image: dashanji/swck-spring-demo:v0.0.3
+ command: ["java"]
+ args: ["-jar","$(AGENT_OPTS)","-jar","/app.jar"]
```
Get injected resources as below:
@@ -132,7 +191,7 @@ spec:
- name: AGENT_OPTS
value: -javaagent:/skytest/agent/skywalking-agent.jar
image: dashanji/swck-spring-demo:v0.0.3
- name: demo
+ name: demo2
- mountPath: /skytest/agent
name: sky-agent
- mountPath: /skytest/agent/config
@@ -152,14 +211,60 @@ spec:
- emptyDir: {}
name: sky-agent
- configMap:
- name: haha
+ name: newconfigmap
name: java-agent-configmap-volume
```
```shell
-$ kubectl get configmap skywalking-swck-java-agent-configmap -n default(your namespace)
-NAME DATA AGE
-skywalking-swck-java-agent-configmap 1 61s
+$ kubectl get configmap newconfigmap -n default
+NAME DATA AGE
+newconfigmap 1 2m29s
+```
+
+Then you can get the final agent configuration and the pod as below.
+
+```shell
+$ kubectl get javaagent
+NAME PODSELECTOR SERVICENAME BACKENDSERVICE
+app-demo2-javaagent app=demo2 Your_ApplicationName 127.0.0.1:11800
+$ kubectl get pod -l app=demo2(the podSelector)
+NAME READY STATUS RESTARTS AGE
+demo2-74b65f98b9-k5wvd 1/1 Running 0 3m28s
+```
+
+Get the javaagent's yaml for more datails.
+
+```shell
+$ kubectl get javaagent app-demo2-javaagent -oyaml
+apiVersion: operator.skywalking.apache.org/v1alpha1
+kind: JavaAgent
+metadata:
+ creationTimestamp: "2021-10-15T05:10:16Z"
+ generation: 1
+ name: app-demo2-javaagent
+ namespace: default
+ ownerReferences:
+ - apiVersion: apps/v1
+ blockOwnerDeletion: true
+ controller: true
+ kind: ReplicaSet
+ name: demo2-74b65f98b9
+ uid: cbc2c680-4f84-469a-bb43-fc48161d6958
+ resourceVersion: "458626"
+ selfLink: /apis/operator.skywalking.apache.org/v1alpha1/namespaces/default/javaagents/app-demo2-javaagent
+ uid: 7c59aab7-30fc-4122-8b39-4cba2d1711b5
+spec:
+ agentConfiguration:
+ agent.service_name: Your_ApplicationName
+ collector.backend_service: 127.0.0.1:11800
+ backendService: 127.0.0.1:11800
+ podSelector: app=demo2
+ serviceName: Your_ApplicationName
+status:
+ creationTime: "2021-10-15T05:10:16Z"
+ expectedInjectiedNum: 1
+ lastUpdateTime: "2021-10-15T05:10:18Z"
+ realInjectedNum: 1
```
#### Use annotation to set the coverage strategy and override the agent configuration
@@ -174,32 +279,41 @@ Then add `swck-java-agent-injected: "true"` in the labels of yaml file and [agen
```
-apiVersion: v1
-kind: Pod
+apiVersion: apps/v1
+kind: Deployment
metadata:
- labels:
- swck-java-agent-injected: "true"
- annotations:
- strategy.skywalking.apache.org/inject.Container: "demo"
- strategy.skywalking.apache.org/agent.Overlay: "true"
- agent.skywalking.apache.org/agent.sample_n_per_3_secs: "6"
- agent.skywalking.apache.org/agent.class_cache_mode: "MEMORY"
- agent.skywalking.apache.org/agent.ignore_suffix: "'jpg,.jpeg'"
- plugins.skywalking.apache.org/plugin.mount: "'plugins,activations'"
- plugins.skywalking.apache.org/plugin.mongodb.trace_param: "true"
- plugins.skywalking.apache.org/plugin.influxdb.trace_influxql: "false"
- optional.skywalking.apache.org: "trace|webflux|cloud-gateway-2.1.x"
- optional-reporter.skywalking.apache.org: "kafka"
- name: inject3
+ name: demo3
namespace: default
spec:
- containers:
- - name: nginx
- image: nginx:1.16.1
- - name: demo
- image: dashanji/swck-spring-demo:v0.0.3
- command: ["java"]
- args: ["-jar","$(AGENT_OPTS)","-jar","/app.jar"]
+ replicas: 3
+ selector:
+ matchLabels:
+ app: demo3
+ template:
+ metadata:
+ name: inject-demo3
+ labels:
+ swck-java-agent-injected: "true"
+ app: demo3
+ annotations:
+ strategy.skywalking.apache.org/inject.Container: "demo"
+ strategy.skywalking.apache.org/agent.Overlay: "true"
+ agent.skywalking.apache.org/agent.service_name: "app"
+ agent.skywalking.apache.org/agent.sample_n_per_3_secs: "6"
+ agent.skywalking.apache.org/agent.class_cache_mode: "MEMORY"
+ agent.skywalking.apache.org/agent.ignore_suffix: "'jpg,.jpeg'"
+ plugins.skywalking.apache.org/plugin.mount: "'plugins,activations'"
+ plugins.skywalking.apache.org/plugin.mongodb.trace_param: "true"
+ plugins.skywalking.apache.org/plugin.influxdb.trace_influxql: "false"
+ optional.skywalking.apache.org: "trace|webflux|cloud-gateway-2.1.x"
+ optional-reporter.skywalking.apache.org: "kafka"
+ namespace: default
+ spec:
+ containers:
+ - name: demo3
+ image: dashanji/swck-spring-demo:v0.0.3
+ command: ["java"]
+ args: ["-jar","$(AGENT_OPTS)","-jar","/app.jar"]
```
Get injected resources as below:
@@ -219,9 +333,9 @@ spec:
- java
env:
- name: AGENT_OPTS
- value: -javaagent:/sky/agent/skywalking-agent.jar=agent.ignore_suffix='jpg,.jpeg',agent.sample_n_per_3_secs=6,agent.class_cache_mode=MEMORY,plugin.mount='plugins,activations',plugin.influxdb.trace_influxql=false,plugin.mongodb.trace_param=true
+ value: -javaagent:/sky/agent/skywalking-agent.jar=agent.ignore_suffix='jpg,.jpeg',agent.class_cache_mode=MEMORY,agent.sample_n_per_3_secs=6,agent.service_name=app,plugin.mount='plugins,activations',plugin.influxdb.trace_influxql=false,plugin.mongodb.trace_param=true
image: dashanji/swck-spring-demo:v0.0.3
- name: demo
+ name: demo3
- mountPath: /sky/agent
name: sky-agent
- mountPath: /sky/agent/config
@@ -253,3 +367,59 @@ $ kubectl get configmap skywalking-swck-java-agent-configmap -n default
NAME DATA AGE
skywalking-swck-java-agent-configmap 1 17s
```
+
+Then you can get the final agent configuration and the pod as below.
+
+```shell
+$ kubectl get javaagent
+NAME PODSELECTOR SERVICENAME BACKENDSERVICE
+app-demo3-javaagent app=demo3 app 127.0.0.1:11800
+$ kubectl get pod -l app=demo3(the podSelector)
+NAME READY STATUS RESTARTS AGE
+demo3-69bff546df-55w8c 1/1 Running 0 57s
+demo3-69bff546df-mn5fq 1/1 Running 0 57s
+demo3-69bff546df-skklk 1/1 Running 0 57s
+```
+
+Get the javaagent's yaml for more datails.
+
+```shell
+$ kubectl get javaagent app-demo3-javaagent -oyaml
+apiVersion: operator.skywalking.apache.org/v1alpha1
+kind: JavaAgent
+metadata:
+ creationTimestamp: "2021-10-15T05:21:06Z"
+ generation: 1
+ name: app-demo3-javaagent
+ namespace: default
+ ownerReferences:
+ - apiVersion: apps/v1
+ blockOwnerDeletion: true
+ controller: true
+ kind: ReplicaSet
+ name: demo3-69bff546df
+ uid: 1f04a239-0247-4f5c-967a-64009adae42c
+ resourceVersion: "461000"
+ selfLink: /apis/operator.skywalking.apache.org/v1alpha1/namespaces/default/javaagents/app-demo3-javaagent
+ uid: be35588e-9b2d-4528-90df-c1a630616632
+spec:
+ agentConfiguration:
+ agent.class_cache_mode: MEMORY
+ agent.ignore_suffix: '''jpg,.jpeg'''
+ agent.sample_n_per_3_secs: "6"
+ agent.service_name: app
+ collector.backend_service: 127.0.0.1:11800
+ optional-plugin: trace|webflux|cloud-gateway-2.1.x
+ optional-reporter-plugin: kafka
+ plugin.influxdb.trace_influxql: "false"
+ plugin.mongodb.trace_param: "true"
+ plugin.mount: '''plugins,activations'''
+ backendService: 127.0.0.1:11800
+ podSelector: app=demo3
+ serviceName: app
+status:
+ creationTime: "2021-10-15T05:21:06Z"
+ expectedInjectiedNum: 3
+ lastUpdateTime: "2021-10-15T05:21:10Z"
+ realInjectedNum: 3
+```
\ No newline at end of file
diff --git a/docs/java-agent-injector.md b/docs/java-agent-injector.md
index 44bab45..5841c23 100644
--- a/docs/java-agent-injector.md
+++ b/docs/java-agent-injector.md
@@ -166,3 +166,7 @@ The injector can recognize the following annotations to configure the sidecar:
| `sidecar.skywalking.apache.org/configmapVolume.ConfigMap.Name` | The name pf configmap used in the injected container as `agent.config ` | `skywalking-swck-java-agent-configmap` |
| `sidecar.skywalking.apache.org/env.Name` | Environment Name used by the injected container (application container). | `AGENT_OPTS` |
| `sidecar.skywalking.apache.org/env.Value` | Environment variables used by the injected container (application container). | `-javaagent:/sky/agent/skywalking-agent.jar` |
+
+## The ways to get the final injected agent's configuration
+
+Please see [javaagent introduction](javaagent.md) for details.
\ No newline at end of file
diff --git a/docs/javaagent.md b/docs/javaagent.md
new file mode 100644
index 0000000..9370d6d
--- /dev/null
+++ b/docs/javaagent.md
@@ -0,0 +1,82 @@
+# JavaAgent Introduction
+
+To see the final injected agent's configuration, we define a CustomDefinitionResource called JavaAgent.
+
+When the pod is injected, the pod will be labeled with `sidecar.skywalking.apache.org/succeed`, then the controller will watch the specific pod labeled with `sidecar.skywalking.apache.org/succeed`. After the pod is created, the controller will create JavaAgent(custom resource), which contains the final agent configuration as below.
+
+## Spec
+
+| Field Name | Description |
+| ------------------ | ------------------------------------------------------------ |
+| podSelector | We hope users can use [workloads](https://kubernetes.io/docs/concepts/workloads/) to create pods, the podSelector is the selector label of workload. |
+| serviceName | serviceName is an important attribute that needs to be printed. |
+| backendService | backendService is an important attribute that needs to be printed. |
+| agentConfiguration | agentConfiguration contains serviceNamećbackendService and covered agent configuration, other default configurations will not be displayed, please see [agent.config](https://skywalking.apache.org/docs/skywalking-java/latest/en/setup/service-agent/java-agent/configurations/#table-of-agent-configuration-properties) for details. |
+
+## Status
+
+| Field Name | Description |
+| -------------------- | ---------------------------------------------- |
+| creationTime | The creation time of the JavaAgent |
+| lastUpdateTime | The last Update time of the JavaAgent |
+| expectedInjectiedNum | The number of the pod that need to be injected |
+| realInjectedNum | The real number of injected pods. |
+
+## Demo
+
+This demo shows the usage of javaagent. If you want to see the complete process, please see [java-agent-injector-usage](examples/java-agent-injector-usage.md)for details.
+
+When we use [java-agent-injector](java-agent-injector.md), we can get custom resources as below.
+
+```
+$ kubectl get javaagent -A
+NAMESPACE NAME PODSELECTOR SERVICENAME BACKENDSERVICE
+default app-demo1-javaagent app=demo1 Your_ApplicationName 127.0.0.1:11800
+default app-demo2-javaagent app=demo2 Your_ApplicationName 127.0.0.1:11800
+$ kubectl get pod -l app=demo1
+NAME READY STATUS RESTARTS AGE
+demo1-bb97b8b4d-bkwm4 1/1 Running 0 28s
+demo1-bb97b8b4d-wxgs2 1/1 Running 0 28s
+$ kubectl get pod -l app=demo2
+NAME READY STATUS RESTARTS AGE
+app2-0 1/1 Running 0 27s
+app2-1 1/1 Running 0 25s
+app2-2 1/1 Running 0 23s
+```
+
+If we want to see more information, we can get the specific javaagent's yaml as below.
+
+```
+$ kubectl get javaagent app-demo1-javaagent -oyaml
+apiVersion: operator.skywalking.apache.org/v1alpha1
+kind: JavaAgent
+metadata:
+ creationTimestamp: "2021-10-14T07:07:12Z"
+ generation: 1
+ name: app-demo1-javaagent
+ namespace: default
+ ownerReferences:
+ - apiVersion: apps/v1
+ blockOwnerDeletion: true
+ controller: true
+ kind: ReplicaSet
+ name: demo1-bb97b8b4d
+ uid: c712924f-4652-4c07-8332-b3938ad72392
+ resourceVersion: "330808"
+ selfLink: /apis/operator.skywalking.apache.org/v1alpha1/namespaces/default/javaagents/app-demo1-javaagent
+ uid: 9350338f-15a5-4832-84d1-530f8d0e1c3b
+spec:
+ agentConfiguration:
+ agent.namespace: default-namespace
+ agent.service_name: Your_ApplicationName
+ collector.backend_service: 127.0.0.1:11800
+ backendService: 127.0.0.1:11800
+ podSelector: app=demo1
+ serviceName: Your_ApplicationName
+status:
+ creationTime: "2021-10-14T07:07:12Z"
+ expectedInjectiedNum: 2
+ lastUpdateTime: "2021-10-14T07:07:14Z"
+ realInjectedNum: 2
+```
+