Skip to content

Commit 626543b

Browse files
andytaelandytael
authored
Documentation update (#1095)
Signed-off-by: Andy Tael <[email protected]>
1 parent 1eaa50f commit 626543b

29 files changed

+476
-19
lines changed

‎docs-source/site/docs/deploy/buildapp.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,5 @@ This content is TBD
1111
These are the steps to deploy the application to ak8s cluster using Helm.
1212

1313
- Obtain the deployment Helm chart from [here](hhtp://where)
14-
- Edit `Values.yaml` to refelct your application
14+
- Edit `Values.yaml` to reflect your application
1515
- Install the Helm chart.

‎docs-source/site/docs/observability/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Observability",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Oracle Backend for Microservices and AI provides built-in platform services to collect and visualize metrics, logs and traces from system and application workloads."
7+
}
8+
}

‎docs-source/site/docs/observability/acces.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Access SigNoz
3+
sidebar_position: 2
4+
---
5+
## How to access SigNoz
6+
7+
1. Get the _admin_ email and password for SigNoz
8+
9+
```shell
10+
kubectl -n observability get secret signoz-authn -o jsonpath='{.data.email}' | base64 -d
11+
kubectl -n observability get secret signoz-authn -o jsonpath='{.data.password}' | base64 -d
12+
```
13+
14+
1. Expose the SigNoz user interface (UI) using this command:
15+
16+
```shell
17+
kubectl -n observability port-forward svc/obaas-signoz-frontend 3301:3301
18+
```
19+
20+
1. Open [SigNoz Login](http://localhost:3301/login) in a browser and login with the _admin_ email and the _password_ you have retrieved.
21+
22+
![SigNoz UI](images/obaas-signoz-ui.png)

‎docs-source/site/docs/observability/configure.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
title: Configure Applications for SigNoz
3+
sidebar_position: 5
4+
---
5+
## Configure applications for SigNoz Observability
6+
7+
In order for SigNoz to be able to collect logs, metrics and traces from applications, some configurations are required to be added.
8+
9+
### Configure OpenTelemetry and Micrometer
10+
11+
[OpenTelemetry zero-code instrumentation](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/getting-started/) enables adding observability to Spring Boot based applications without changing any code. Similarly [Micrometer](https://docs.micrometer.io/micrometer/reference/observation/projects.html) enables instrumentation of JVM based applications and can be configured using Spring Boot starters.
12+
13+
:::note
14+
The versions in the below pom.xml might be outdated.
15+
:::
16+
17+
```xml
18+
<dependencies>
19+
<dependency>
20+
<groupId>io.micrometer</groupId>
21+
<artifactId>micrometer-core</artifactId>
22+
</dependency>
23+
<dependency>
24+
<groupId>io.micrometer</groupId>
25+
<artifactId>micrometer-registry-prometheus</artifactId>
26+
</dependency>
27+
<dependency>
28+
<groupId>io.micrometer</groupId>
29+
<artifactId>micrometer-tracing-bridge-otel</artifactId>
30+
<exclusions>
31+
<exclusion>
32+
<groupId>io.opentelemetry.instrumentation</groupId>
33+
<artifactId>opentelemetry-instrumentation-api-incubator</artifactId>
34+
</exclusion>
35+
</exclusions>
36+
</dependency>
37+
<dependency>
38+
<groupId>io.opentelemetry</groupId>
39+
<artifactId>opentelemetry-exporter-otlp</artifactId>
40+
</dependency>
41+
<dependency>
42+
<groupId>io.micrometer</groupId>
43+
<artifactId>micrometer-tracing</artifactId>
44+
</dependency>
45+
<dependency>
46+
<groupId>io.opentelemetry.instrumentation</groupId>
47+
<artifactId>opentelemetry-spring-boot-starter</artifactId>
48+
</dependency>
49+
<dependency>
50+
<groupId>net.ttddyy.observation</groupId>
51+
<artifactId>datasource-micrometer-spring-boot</artifactId>
52+
</dependency>
53+
<dependency>
54+
<groupId>com.oracle.database.spring</groupId>
55+
<artifactId>oracle-spring-boot-starter-ucp</artifactId>
56+
<type>pom</type>
57+
</dependency>
58+
<dependency>
59+
<groupId>io.opentelemetry.instrumentation</groupId>
60+
<artifactId>opentelemetry-oracle-ucp-11.2</artifactId>
61+
</dependency>
62+
</dependencies>
63+
64+
<dependencyManagement>
65+
<dependencies>
66+
<dependency>
67+
<groupId>io.opentelemetry.instrumentation</groupId>
68+
<artifactId>opentelemetry-instrumentation-bom</artifactId>
69+
<type>pom</type>
70+
<scope>import</scope>
71+
</dependency>
72+
<dependency>
73+
<groupId>io.micrometer</groupId>
74+
<artifactId>micrometer-tracing-bom</artifactId>
75+
<version>${micrometer-tracing.version}</version>
76+
<type>pom</type>
77+
<scope>import</scope>
78+
</dependency>
79+
</dependencies>
80+
</dependencyManagement>
81+
```
82+
83+
### Configure Datasource Observability
84+
85+
[datasource-micrometer](https://github.com/jdbc-observations/datasource-micrometer) and [Oracle Universal Connection Pool Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/oracle-ucp-11.2) can be configured to enable observability for Database connections and queries.
86+
87+
:::note
88+
The versions in the below pom.xml might be outdated.
89+
:::
90+
91+
```xml
92+
<dependencies>
93+
<dependency>
94+
<groupId>net.ttddyy.observation</groupId>
95+
<artifactId>datasource-micrometer-spring-boot</artifactId>
96+
</dependency>
97+
<dependency>
98+
<groupId>io.opentelemetry.instrumentation</groupId>
99+
<artifactId>opentelemetry-oracle-ucp-11.2</artifactId>
100+
</dependency>
101+
</dependencies>
102+
```
103+
104+
### Configure Spring Boot Actuator
105+
106+
When you deploy an application with Oracle Backend for Microservices and AI CLI or Visual Code Extension, provided you included the Spring Actuator in your application, SigNoz will automatically find your application (using the annotations) and start collecting metrics. These metrics will be included in both the Spring Boot Observability dashboard and the Spring Boot Statistic dashboard automatically.
107+
108+
To include the Actuator in your application, add the following dependencies to your Maven POM or equivalent:
109+
110+
```xml
111+
<dependency>
112+
<groupId>org.springframework.boot</groupId>
113+
<artifactId>spring-boot-starter-actuator</artifactId>
114+
</dependency>
115+
```
116+
117+
You must also add the configuration similar to one given below, after customizing it for your application, to your Spring `application.yaml`
118+
119+
```yaml
120+
spring:
121+
threads:
122+
virtual:
123+
enabled: true
124+
jpa:
125+
hibernate:
126+
ddl-auto: validate
127+
properties:
128+
hibernate:
129+
dialect: org.hibernate.dialect.OracleDialect
130+
format_sql: true
131+
show-sql: true
132+
133+
eureka:
134+
instance:
135+
hostname: ${spring.application.name}
136+
preferIpAddress: true
137+
client:
138+
service-url:
139+
defaultZone: ${eureka.service-url}
140+
fetch-registry: true
141+
register-with-eureka: true
142+
enabled: true
143+
144+
management:
145+
endpoint:
146+
health:
147+
show-details: always
148+
show-components: always
149+
endpoints:
150+
web:
151+
exposure:
152+
include: "*"
153+
metrics:
154+
tags:
155+
application: ${spring.application.name}
156+
distribution:
157+
percentiles[http.server.requests]: 0.5, 0.90, 0.95, 0.99
158+
percentiles-histogram[http.server.requests]: true
159+
slo[http.server.requests]: 100ms, 250ms, 500ms, 1s, 2s, 5s, 10s, 30s
160+
percentiles[http.client.requests]: 0.5, 0.90, 0.95, 0.99
161+
percentiles-histogram[http.client.requests]: true
162+
slo[http.client.requests]: 100ms, 250ms, 500ms, 1s, 2s, 5s, 10s, 30s
163+
health:
164+
probes:
165+
enabled: true
166+
tracing:
167+
sampling:
168+
probability: 1.0
169+
info:
170+
os:
171+
enabled: true
172+
env:
173+
enabled: true
174+
java:
175+
enabled: true
176+
observations:
177+
key-values:
178+
app: ${spring.application.name}
179+
180+
logging:
181+
level:
182+
root: INFO
183+
com.example: INFO
184+
org.springframework.web.filter.AbstractRequestLoggingFilter: INFO
185+
186+
jdbc:
187+
datasource-proxy:
188+
query:
189+
enable-logging: true
190+
log-level: INFO
191+
include-parameter-values: true
192+
```
193+
194+
The Oracle Backend for Microservices and AI platform adds following annotations to your application pods for SigNoz to start scraping the actuator endpoint for metrics.
195+
196+
```yaml
197+
signoz.io/path: /actuator/prometheus
198+
signoz.io/port: "8080"
199+
signoz.io/scrape: "true"
200+
```
201+
202+
It also adds the `OTEL_EXPORTER_OTLP_ENDPOINT` to pod environment variables for the OpenTelemetry instrumentation libraries to access the the OpenTelemtry collector of SigNoz.
203+
204+
```yaml
205+
- name: OTEL_EXPORTER_OTLP_ENDPOINT
206+
value: http://obaas-signoz-otel-collector.observability:4318
207+
```

‎docs-source/site/docs/observability/dashboards.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Pre-installed dashboards
3+
sidebar_position: 4
4+
---
5+
:::note
6+
More details can be found in the [SigNoz Documentation](https://signoz.io/docs/introduction/).
7+
:::
8+
9+
## Pre-installed dashboards
10+
11+
The following dashboards are pre-installed in SigNoz:
12+
13+
- [Spring Boot Observability](#spring-boot-observability)
14+
- [Spring Boot Observability](#spring-boot-observability)
15+
- [Spring Boot Statistics](#spring-boot-statistics)
16+
- [Oracle Database Dashboard](#oracle-database-dashboard)
17+
- [Kube State Metrics Dashboard](#kube-state-metrics-dashboard)
18+
- [Apache APISIX Dashboard](#apache-apisix-dashboard)
19+
20+
### Spring Boot Observability
21+
22+
This dashboard provides details of one or more Spring Boot applications including the following:
23+
24+
- The number of HTTP requests received by the application
25+
- A breakdown of which URL paths requests were received for
26+
- The average duration of requests by path
27+
- The number of exceptions encountered by the application
28+
- Details of 2xx (that is, successful) and 5xx (that is, exceptions) requests
29+
- The request rate per second over time, by path
30+
- Log messages from the service
31+
32+
You may adjust the time period and to drill down into issues, and search the logs for particular messages. This dashboard is designed for Spring Boot 3.x applications. Some features may work for Spring Boot 2.x applications.
33+
34+
Here is an example of this dashboard displaying data for a simple application:
35+
36+
![Spring Boot Observability Dashboard](images/spring-boot-observability-dashboard.png)
37+
38+
### Spring Boot Statistics
39+
40+
This dashboard provides more in-depth information about services including the following:
41+
42+
- JVM statistic like heap and non-heap memory usage, and details of garbage collection
43+
- Load average and open files
44+
- Database connection pool statistics (for HikariCP)
45+
- HTTP request statistics
46+
- Logging (logback) statistics
47+
48+
You may adjust the time period and to drill down into issues, and search the logs for particular messages. This dashboard is designed for Spring Boot 3.x applications. Some features may work for Spring Boot 2.x applications.
49+
50+
Here is an example of this dashboard displaying data for a simple application:
51+
52+
![Spring Boot Stats Dashboard](images/spring-boot-stats-dashboard.png)
53+
54+
### Oracle Database Dashboard
55+
56+
This dashboard provides details about the Oracle Database including:
57+
58+
- SGA and PGA size
59+
- Active sessions
60+
- User commits
61+
- Execute count
62+
- CPU count and platform
63+
- Top SQL
64+
- Wait time statistics by class
65+
66+
Here is an example of this dashboard:
67+
68+
![Oracle Database Dashboard](images/db-dashboard.png)
69+
70+
### Kube State Metrics Dashboard
71+
72+
This dashboard provides details of the Kubernetes cluster including:
73+
74+
- Pod capacity and requests for CPU and memory
75+
- Node availability
76+
- Deployment, Stateful Set, Pod, Job and Container statistics
77+
- Details of horizontal pod autoscalers
78+
- Details of persistent volume claims
79+
80+
Here is an example of this dashboard:
81+
82+
![Kube State Metrics Dashboard](images/kube-state-metrics-dashboard.png)
83+
84+
### Apache APISIX Dashboard
85+
86+
This dashboard provides details of the APISIX API Gateway including:
87+
88+
- Total Requests
89+
- NGINX Connection State
90+
- Etcd modifications
91+
92+
Here is an example of this dashboard:
93+
94+
![Apache APISIX Dashboard](images/apache-apisix-dashboard.png)

‎docs-source/site/docs/observability/dbexporter.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Oracle Database Metrics Exporter
3+
sidebar_position: 6
4+
---
5+
## Oracle Database Metrics Exporter
6+
7+
Oracle Database Metrics Exporter aims to provide observability for the Oracle Database so that users can understand performance and diagnose issues easily across applications and database. Oracle Database Metrics Exporter deliver functionality to support both cloud and on-premises databases, including those running in Kubernetes and containers.
8+
9+
See the [documentation](https://oracle.github.io/oracle-db-appdev-monitoring/) for how to install and configure Oracle Database Metrics Exporter.

‎docs-source/site/docs/observability/images/apache-apisix-dashboard.png‎

148 KB
Loading

‎docs-source/site/docs/observability/images/db-dashboard.png‎

214 KB
Loading

‎docs-source/site/docs/observability/images/kube-state-metrics-dashboard.png‎

157 KB
Loading

‎docs-source/site/docs/observability/images/obaas-signoz-ui.png‎

168 KB
Loading

0 commit comments

Comments
 (0)