Skip to content

Commit 48fe161

Browse files
predix-adoption-botpredix-adoption-bot
committed
Release 1.0.0
1 parent 7b0adb2 commit 48fe161

98 files changed

Lines changed: 8559 additions & 2 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 232 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,232 @@
1-
# audit-sdk
1+
<a href="../../../../pages/adoption/audit-sdk/javadocs/index.html" target="_blank" >
2+
<img height="50px" width="100px" src="images/javadoc.png" alt="view javadoc"></a>
3+
&nbsp;
4+
<a href="../../../../pages/adoption/audit-sdk" target="_blank">
5+
<img height="50px" width="100px" src="images/pages.jpg" alt="view github pages">
6+
</a>
7+
8+
# audit-sdk
9+
10+
Audit Service Java SDK
11+
12+
Use the SDK to publish audit messages using the Audit client.
13+
14+
----------
15+
16+
## How to use the Audit Service SDK
17+
- Add the below dependency to your maven pom XML file
18+
```
19+
<dependency>
20+
<groupId>com.ge.predix</groupId>
21+
<artifactId>audit-sdk</artifactId>
22+
<version>1.0.0</version>
23+
</dependency>
24+
```
25+
26+
## Initializing the client
27+
28+
Prior to creating the auditClient, you need to create an AuditConfiguration.
29+
30+
With this configuration you can create a Sync or Async audit clients.
31+
32+
#### Audit Configuration
33+
The AuditConfiguration exposes provisioning parameters of the audit client.
34+
35+
AuditConfiguration can be constructed manually or automatically:
36+
37+
**Use the VcapLoaderServiceImpl to automatically create your configuration.**
38+
```
39+
private VcapLoaderServiceImpl vcapLoaderService = new VcapLoaderServiceImpl();
40+
private AuditConfiguration auditConfiguration = vcapLoaderService.getConfigFromVcap();
41+
```
42+
Automatic mode requires that your application will be bound to the predix-audit service instance.
43+
It also requires to set the following environment variables in you application:
44+
+ `AUDIT_SERVICE_NAME`: The name of the AuditService in the cf marketplace.
45+
+ `AUDIT_UAA_URL`: https://<UAA instance>.predix-uaa.run.aws-usw02-dev.ice.predix.io/oauth/token.
46+
+ `AUDIT_UAA_CLIENT_ID`: The UAA client for Audit Service.
47+
+ `AUDIT_UAA_CLIENT_SECRET`: The UAA secret of above client.
48+
49+
Example manifest.yml:
50+
51+
```
52+
---
53+
applications:
54+
- name: my-auditing-application
55+
instances: 1
56+
services:
57+
- my-audit-service
58+
env:
59+
AUDIT_SERVICE_NAME: predix-audit
60+
AUDIT_UAA_URL: https://2e6f8552-acb2-4d96-b470-0d44fe8cd33b.predix-uaa.run.asv-pr.ice.predix.io/oauth/token
61+
AUDIT_UAA_CLIENT_ID: client
62+
AUDIT_UAA_CLIENT_SECRET: secret
63+
```
64+
65+
Additional optional parameters can be supplied through VCAP to control the client configuration:
66+
+ `AUDIT_MAX_RETRY_COUNT`: The number of attempts made to resend a failed audit.
67+
- Valid values: 0-5. default: 2.
68+
+ `AUDIT_RETRY_INTERVAL_MILLIS`: The amount of time in milliseconds between each retry attempt.
69+
- Valid values: 2,000 - 20,000 (2 sec - 20 sec). default - 10,000.
70+
+ `AUDIT_MAX_CACHED_EVENTS`: The maximum number of events cached im memory, waiting to be sent.
71+
- Default: 50,000. minimum value is 1000.
72+
+ `AUDIT_RECONNECT_POLICY`: Controls whether the Audit client will attempt a reconnect when disconnected.
73+
- Valid values: MANUEL, AUTOMATIC. default: MANUEL - no reconnect attempt is made.
74+
75+
**Use one of the `AuditConfiguration` builders to create the configuration manually:**.
76+
+ `AuditConfigurationBuilder` (`AuditConfiguration.builder()`) to create a client with uaa user / pass for authentication.
77+
+ `AuditConfigurationWithAuthTokenBuilder` (`AuditConfiguration.builderWithAuthToken()`) to create a client with Auth token.
78+
79+
80+
#### Audit Client
81+
82+
You can create two types of clients:
83+
- Sync client - requires AuditConfiguration.
84+
- Async Client - requires AuditConfiguration and AuditCallback.
85+
86+
You should create the client according to the desired mode.
87+
88+
For async client:
89+
```
90+
AuditClient auditClient = new AuditClient(configuration , callback)
91+
```
92+
93+
For sync client:
94+
```
95+
AuditClientSync auditClientSync = new AuditClient(configuration)
96+
```
97+
**Be aware AuditClientType.SYNC is deprecated and should not be used to indicate the client mode**
98+
99+
## Client API
100+
101+
The AuditClient and AuditClientSync share a similar API. they only differ in the way they expose the results of the audit operation.
102+
103+
#### Publishing audit events
104+
105+
To publish event you can use the
106+
`auditClient.audit(AuditEvent)` or
107+
`auditClient.audit(List<AuditEvent>)`
108+
109+
Here is an example:
110+
111+
```
112+
AuditEvent eventV2 = AuditEventV2.builder()
113+
.payload("This is test payload")
114+
.classifier(AuditEnums.Classifier.FAILURE)
115+
.publisherType(AuditEnums.PublisherType.APP_SERVICE)
116+
.categoryType(AuditEnums.CategoryType.API_CALLS)
117+
.eventType(AuditEnums.EventType.FAILURE_API_REQUEST)
118+
.tenantUuid(UUID.randomUUID().toString())
119+
.correlationId(UUID.randomUUID().toString())
120+
.appName(applicationName)
121+
.build();
122+
123+
auditClient.audit(eventV2);
124+
```
125+
126+
#### Handling the results
127+
128+
##### Asynchronous client
129+
130+
The results of the audit operation, as well as other client related info are propagated through the AuditCallback.
131+
132+
You should implement the AuditCallback interface and supply the auditClient with the implementation.
133+
```
134+
public AuditCallback auditCallback(){
135+
return new AuditCallback() {
136+
@Override
137+
public void onValidate(AuditEvent auditEvent, List<ValidatorReport> list) {
138+
log.info("onValidate {}", list);
139+
}
140+
141+
@Override
142+
public void onFailure(AuditEvent auditEvent, FailReport failReport, String description) {
143+
log.info("onFailure {} \n {} \n {}", failReport, auditEvent, description);
144+
}
145+
146+
@Override
147+
public void onFailure(FailReport failReport, String description) {
148+
log.info("onFailure {} \n {}", failReport, description);
149+
}
150+
151+
@Override
152+
public void onSuccees(AuditEvent auditEvent) {
153+
log.info("onSuccees {}", auditEvent);
154+
}
155+
};
156+
}
157+
```
158+
159+
##### Synchronous client
160+
The results of the audit operation are returned with the AuditingResult. It contains the following elements:
161+
```
162+
List<AuditEventFailReport> failedEvents;
163+
List<AuditEvent> sentEvents;
164+
```
165+
Each `AuditEventFailReport` contains the failed event, a `FailReport` status code, and a failure description.
166+
167+
`FailReport` indicates the type of error encountered.
168+
169+
When returned with an event (i.e. `onFailure(event, failReport, description)` ) it can take one of the following values:
170+
+ 'BAD_ACK' - NACK was received. The description contains the ack details.
171+
+ 'NO_ACK' - no ACK was received after max retry attempts was made.
172+
+ 'CACHE_IS_FULL' - the Audit cache is full and the event had to be dropped.
173+
174+
175+
#### Additional API
176+
177+
##### Reconnect option
178+
Occasionally, audit client can be disconnected. In such a case, you receive an ```onFailure``` callback with ```FailReport.STREAM_IS_CLOSE```
179+
**This notification is currently available only for ASYNC mode**.
180+
181+
There are two ways to handle reconnection:
182+
+ MANUAL (default) - the `auditClient.reconnect()` API should be used to re-establish the connection.
183+
+ AUTOMATIC - no API call is needed. the sdk automatically reconnects until the connection is restored.
184+
185+
Use the configuration to change the reconnect mode:
186+
```
187+
AuditConfiguration.builder()
188+
.reconnectMode(ReconnectMode.AUTOMATIC)
189+
.build()
190+
```
191+
##### Authentication token
192+
The sdk supports two modes of authentication:
193+
- Using a UAA user and pass. Use the `AuditConfiguration.builder()` to obtain a regular, UAA based configuration.
194+
- Using an authentication token. Use the `AuditConfiguration.builderWithAuthToken()` to obtain an auth token based configuration.
195+
196+
Once a client was created, its authentication mode cannot be changed.
197+
When working with authentication token, you might need to refresh the token. This can be achieved by running the `auditClient.setAuthToken(token)` API.
198+
199+
Please note that this API throws IllegalStateException if executed on a client configured with UAA authentication mode.
200+
201+
----
202+
## Additional information
203+
204+
##### Debug flag
205+
You can enable audit debug log level by setting `AUDIT_DEBUG_ENABLED: true` in your environment.
206+
207+
##### Tracing abilities
208+
The SDK audits a marked message once every few minutes. The message is not sent to your DB and is for debugging purposes. This feature may be disabled in the configuration:
209+
```
210+
AuditConfiguration.builder()
211+
.traceEnabled(false)
212+
.build()
213+
```
214+
##### Auditing Application Name
215+
When building an auditEvent (V2 and up), you can add the auditing application name. This is a friendly name that can take a String up to 100 characters.
216+
```
217+
AuditConfiguration.builder()
218+
.appName("application name")
219+
.build()
220+
```
221+
If APPLICATION_NAME variable was set in the environment, it will be added to each message and there is no need to explicitly provide it when building the message.
222+
223+
#### For more information about the api: https://docs.predix.io/en-US/content/service/security/audit/using-predix-audit-service
224+
225+
----
226+
# Example Projects:
227+
- https://github.com/PredixDev/samplePublisherApp
228+
- https://github.com/PredixDev/samplePub-POJO
229+
230+
231+
[![Analytics](https://ga-beacon.appspot.com/UA-82773213-1/audit-sdk/readme?pixel)](https://github.com/PredixDev)
232+

‎_config.yml‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎images/javadoc.png‎

6.28 KB
Loading

‎images/pages.jpg‎

4.1 KB
Loading

0 commit comments

Comments
 (0)