Skip to content

Commit 8f9f01e

Browse files
mziccardmziccard
committed
Add complete README and package-info for logging (#1119)
1 parent f9a2d1a commit 8f9f01e

2 files changed

Lines changed: 208 additions & 12 deletions

File tree

‎gcloud-java-logging/README.md‎

Lines changed: 146 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1-
Google Cloud Java Client for Logging
1+
Google Cloud Java Client for Logging (Alpha)
22
====================================
33

4-
Java idiomatic client for [Google Cloud Logging][cloud-logging].
4+
Java idiomatic client for [Stackdriver Logging][stackdriver-logging].
55

66
[![Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-java.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/gcloud-java)
77
[![Coverage Status](https://coveralls.io/repos/GoogleCloudPlatform/gcloud-java/badge.svg?branch=master)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-java?branch=master)
88
[![Maven](https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-logging.svg)]( https://img.shields.io/maven-central/v/com.google.gcloud/gcloud-java-logging.svg)
9+
[![Codacy Badge](https://api.codacy.com/project/badge/grade/9da006ad7c3a4fe1abd142e77c003917)](https://www.codacy.com/app/mziccard/gcloud-java)
10+
[![Dependency Status](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969/badge.svg?style=flat)](https://www.versioneye.com/user/projects/56bd8ee72a29ed002d2b0969)
911

1012
- [Homepage] (https://googlecloudplatform.github.io/gcloud-java/)
1113
- [API Documentation] (http://googlecloudplatform.github.io/gcloud-java/apidocs)
@@ -15,32 +17,155 @@ Java idiomatic client for [Google Cloud Logging][cloud-logging].
1517
1618
Quickstart
1719
----------
20+
21+
> `gcloud-java-logging` uses gRPC as transport layer, which is not (yet) supported by App Engine
22+
Standard. `gcloud-java-logging` will work on App Engine Flexible.
23+
1824
Add this to your pom.xml file
1925
```xml
2026
<dependency>
2127
<groupId>com.google.gcloud</groupId>
2228
<artifactId>gcloud-java-logging</artifactId>
23-
<version>0.0.10</version>
29+
<version>0.2.5</version>
2430
</dependency>
2531
```
32+
If you are using Gradle, add this to your dependencies
33+
```Groovy
34+
compile 'com.google.cloud:gcloud-java-logging:0.2.5'
35+
```
36+
If you are using SBT, add this to your dependencies
37+
```Scala
38+
libraryDependencies += "com.google.cloud" % "gcloud-java-logging" % "0.2.5"
39+
```
2640

2741
Example Application
2842
-------------------
29-
TODO
43+
[`LoggingExample`](../gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/LoggingExample.java)
44+
is a simple command line interface that provides some of Stackdriver Logging's functionality. Read
45+
more about using the application on the
46+
[`LoggingExample` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/cloud/examples/logging/LoggingExample.html).
3047

3148
Authentication
3249
--------------
3350

3451
See the [Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) section in the base directory's README.
3552

36-
About Google Cloud Logging
53+
About Stackdriver Logging
3754
--------------------------
3855

39-
[Google Cloud Logging][cloud-logging] collections and stores logs
40-
from applications and services on the Google Cloud Platform.
56+
[Stackdriver Logging][stackdriver-logging] allows you to store, search, analyze, monitor, and alert
57+
on log data and events from Google Cloud Platform and Amazon Web Services (AWS). Logging is a
58+
fully-managed service that performs at scale and can ingest application and system log data from
59+
thousands of VMs. Even better, you can analyze all that log data in real-time.
60+
61+
See the [Stackdriver Logging docs][stackdriver-logging-quickstart] for more details on how to
62+
activate Logging for your project.
63+
64+
See the ``gcloud-java`` API [Logging documentation][logging-api] to learn how to interact with the
65+
Stackdriver Logging using this Client Library.
66+
67+
Getting Started
68+
---------------
69+
#### Prerequisites
70+
For this tutorial, you will need a
71+
[Google Developers Console](https://console.developers.google.com/) project with the Logging API
72+
enabled. You will need to [enable billing](https://support.google.com/cloud/answer/6158867?hl=en) to
73+
use Stackdriver Logging.
74+
[Follow these instructions](https://cloud.google.com/docs/authentication#preparation) to get your
75+
project set up. You will also need to set up the local development environment by [installing the
76+
Google Cloud SDK](https://cloud.google.com/sdk/) and running the following commands in command line:
77+
`gcloud auth login` and `gcloud config set project [YOUR PROJECT ID]`.
78+
79+
#### Installation and setup
80+
You'll need to obtain the `gcloud-java-logging` library. See the [Quickstart](#quickstart) section
81+
to add `gcloud-java-logging` as a dependency in your code.
82+
83+
#### Creating an authorized service object
84+
To make authenticated requests to Stackdriver Logging, you must create a service object with
85+
credentials. You can then make API calls by calling methods on the Logging service object. The
86+
simplest way to authenticate is to use
87+
[Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).
88+
These credentials are automatically inferred from your environment, so you only need the following
89+
code to create your service object:
90+
91+
```java
92+
import com.google.cloud.logging.Logging;
93+
import com.google.cloud.logging.LoggingOptions;
94+
95+
LoggingOptions options = LoggingOptions.defaultInstance();
96+
try(Logging logging = options.service()) {
97+
// use logging here
98+
}
99+
```
100+
101+
For other authentication options, see the
102+
[Authentication](https://github.com/GoogleCloudPlatform/gcloud-java#authentication) page.
103+
104+
#### Creating a metric
105+
With Logging you can create logs-based metrics. Logs-based metrics allow to keep track of the number
106+
of log messages associated to specific events. Add the following imports at the top of your file:
107+
108+
```java
109+
import com.google.cloud.logging.Metric;
110+
import com.google.cloud.logging.MetricInfo;
111+
```
112+
Then, to create the metric, use the following code:
113+
114+
```java
115+
MetricInfo metricInfo = MetricInfo.builder("test-metric", "severity >= ERROR")
116+
.description("Log entries with severity higher or equal to ERROR")
117+
.build();
118+
logging.create(metricInfo);
119+
```
120+
121+
#### Writing log entries
122+
With Logging you can also write custom log entries. Add the following imports at the top of your
123+
file:
124+
```java
125+
import com.google.cloud.MonitoredResource;
126+
import com.google.cloud.logging.LogEntry;
127+
import com.google.cloud.logging.Logging;
128+
import com.google.cloud.logging.Payload.StringPayload;
41129

42-
TODO: link to docs on activating Logging, high-level documentation on
43-
the API, and code snippet
130+
import java.util.Collections;
131+
```
132+
Then, to write the log entries, use the following code:
133+
```java
134+
LogEntry firstEntry = LogEntry.builder(StringPayload.of("message"))
135+
.logName("test-log")
136+
.resource(MonitoredResource.builder("global")
137+
.addLabel("project_id", options.projectId())
138+
.build())
139+
.build();
140+
logging.write(Collections.singleton(firstEntry));
141+
```
142+
143+
#### Add a Stackdriver Logging handler to a logger
144+
You can also register a `LoggingHandler` to a `java.util.logging.Logger` that publishes log entries
145+
to Stackdriver Logging. Given the following logger:
146+
```java
147+
private final static Logger LOGGER = Logger.getLogger(MyClass.class.getName());
148+
```
149+
You can register a `LoggingHandler` with the code:
150+
```java
151+
LoggingHandler.addHandler(LOGGER, new LoggingHandler());
152+
```
153+
After that, logs generated using `LOGGER` will be also directed to Stackdriver Logging.
154+
155+
Notice that you can also register a `LoggingHandler` via the `logging.properties` configuration
156+
file. Adding, for instance, the following line:
157+
```
158+
com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler
159+
```
160+
#### Complete source code
161+
162+
In
163+
[CreateAndListMetrics.java](../gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/CreateAndListMetrics.java),
164+
[WriteAndListLogEntries.java](../gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/WriteAndListLogEntries.java)
165+
and
166+
[AddLoggingHandler.java](../gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/AddLoggingHandler.java)
167+
we put together all the code shown above into three programs. The programs assume that you are
168+
running on Compute Engine or from your own desktop.
44169

45170
Java Versions
46171
-------------
@@ -50,7 +175,9 @@ Java 7 or above is required for using this client.
50175
Testing
51176
-------
52177

53-
TODO
178+
This library has tools to help make tests for code using Stackdriver Logging.
179+
180+
See [TESTING] to read more about testing.
54181

55182
Versioning
56183
----------
@@ -66,7 +193,9 @@ Contributing
66193

67194
Contributions to this library are always welcome and highly encouraged.
68195

69-
See [CONTRIBUTING] for more information on how to get started.
196+
See `gcloud-java`'s [CONTRIBUTING] documentation and the `gcloud-*` [shared documentation](https://github.com/GoogleCloudPlatform/gcloud-common/blob/master/contributing/readme.md#how-to-contribute-to-gcloud) for more information on how to get started.
197+
198+
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct][code-of-conduct] for more information.
70199

71200
License
72201
-------
@@ -75,6 +204,11 @@ Apache 2.0 - See [LICENSE] for more information.
75204

76205

77206
[CONTRIBUTING]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CONTRIBUTING.md
207+
[code-of-conduct]:https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/CODE_OF_CONDUCT.md#contributor-code-of-conduct
78208
[LICENSE]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/LICENSE
209+
[TESTING]: https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/TESTING.md#testing-code-that-uses-logging
210+
79211

80-
[cloud-logging]: https://cloud.google.com/logging
212+
[stackdriver-logging]: https://cloud.google.com/logging
213+
[stackdriver-logging-quickstart]: https://cloud.google.com/logging/docs/quickstart-sdk
214+
[logging-api]: http://googlecloudplatform.github.io/gcloud-java/apidocs/index.html?com/google/cloud/logging/package-summary.html

‎gcloud-java-logging/src/main/java/com/google/cloud/logging/package-info.java‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
/*
2+
* Copyright 2016 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/**
18+
* A client to Stackdriver Logging.
19+
*
20+
* <p>Here's a simple usage example for using gcloud-java from Compute Engine/App Engine Flexible.
21+
* This example shows how to write and list log entries. For the complete source code see
22+
* <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/WriteAndListLogEntries.java">
23+
* WriteAndListLogEntries.java</a>.
24+
* <pre> {@code
25+
* LoggingOptions options = LoggingOptions.defaultInstance();
26+
* try(Logging logging = options.service()) {
27+
*
28+
* LogEntry firstEntry = LogEntry.builder(StringPayload.of("message"))
29+
* .logName("test-log")
30+
* .resource(MonitoredResource.builder("global")
31+
* .addLabel("project_id", options.projectId())
32+
* .build())
33+
* .build();
34+
* logging.write(Collections.singleton(firstEntry));
35+
*
36+
* Page<LogEntry> entries = logging.listLogEntries(
37+
* EntryListOption.filter("logName=projects/" + options.projectId() + "/logs/test-log"));
38+
* Iterator<LogEntry> entryIterator = entries.iterateAll();
39+
* while (entryIterator.hasNext()) {
40+
* System.out.println(entryIterator.next());
41+
* }
42+
* }}</pre>
43+
*
44+
* <p>This second example shows how to use a {@link java.util.logging.Logger} to write log entries
45+
* to Stackdriver Logging. The snippet installs a Stackdriver Logging handler using
46+
* {@code LoggingHandler.addHandler(Logger, LoggingHandler)}. Notice that this could also be done
47+
* through the {@code logging.properties} file, adding the following line:
48+
* <pre>
49+
* {@code com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler}
50+
* </pre>
51+
* For the complete source code see
52+
* <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/AddLoggingHandler.java">
53+
* AddLoggingHandler.java</a>.
54+
* <pre> {@code
55+
* Logger logger = Logger.getLogger(AddLoggingHandler.class.getName());
56+
* LoggingHandler.addHandler(logger, new LoggingHandler());
57+
* logger.warning("test warning");
58+
* }</pre>
59+
*
60+
* @see <a href="https://cloud.google.com/logging/">Stackdriver Logging</a>
61+
*/
62+
package com.google.cloud.logging;

0 commit comments

Comments
 (0)