Support extended pod logging options

Increase the supported controls on pod logging. Add validaiton to pod
log options. Ensure the Kubelet is using a consistent, structured way to
process pod log arguments.

Add ?sinceSeconds=<durationInSeconds>, &sinceTime=<RFC3339>, ?timestamps=<bool>,
?tailLines=<number>, and ?limitBytes=<number>

api/swagger-spec/v1.json

@@ -6062,6 +6062,46 @@
         "required": false,
         "allowMultiple": false
        },
+       {
+        "type": "*int64",
+        "paramType": "query",
+        "name": "sinceSeconds",
+        "description": "A relative time in seconds before the current time from which to show logs. If this value precedes the time a pod was started, only logs since the pod start will be returned. If this value is in the future, no logs will be returned. Only one of sinceSeconds or sinceTime may be specified.",
+        "required": false,
+        "allowMultiple": false
+       },
+       {
+        "type": "*unversioned.Time",
+        "paramType": "query",
+        "name": "sinceTime",
+        "description": "An RFC3339 timestamp from which to show logs. If this value preceeds the time a pod was started, only logs since the pod start will be returned. If this value is in the future, no logs will be returned. Only one of sinceSeconds or sinceTime may be specified.",
+        "required": false,
+        "allowMultiple": false
+       },
+       {
+        "type": "boolean",
+        "paramType": "query",
+        "name": "timestamps",
+        "description": "If true, add an RFC3339 or RFC3339Nano timestamp at the beginning of every line of log output. Defaults to false.",
+        "required": false,
+        "allowMultiple": false
+       },
+       {
+        "type": "*int64",
+        "paramType": "query",
+        "name": "tailLines",
+        "description": "If set, the number of lines from the end of the logs to show. If not specified, logs are shown from the creation of the container or sinceSeconds or sinceTime",
+        "required": false,
+        "allowMultiple": false
+       },
+       {
+        "type": "*int64",
+        "paramType": "query",
+        "name": "limitBytes",
+        "description": "If set, the number of bytes to read from the server before terminating the log output. This may not display a complete final line of logging, and may return slightly more or slightly less than the specified limit.",
+        "required": false,
+        "allowMultiple": false
+       },
        {
         "type": "string",
         "paramType": "path",

contrib/completions/bash/kubectl

@@ -533,8 +533,13 @@ _kubectl_logs()
     flags+=("--follow")
     flags+=("-f")
     flags+=("--interactive")
+    flags+=("--limit-bytes=")
     flags+=("--previous")
     flags+=("-p")
+    flags+=("--since=")
+    flags+=("--since-time=")
+    flags+=("--tail=")
+    flags+=("--timestamps")
 
     must_have_one_flag=()
     must_have_one_noun=()

docs/man/man1/kubectl-logs.1

@@ -29,10 +29,30 @@ Print the logs for a container in a pod. If the pod has only one container, the
 \fB\-\-interactive\fP=true
     If true, prompt the user for input when required. Default true.
 
+.PP
+\fB\-\-limit\-bytes\fP=0
+    Maximum bytes of logs to return. Defaults to no limit.
+
 .PP
 \fB\-p\fP, \fB\-\-previous\fP=false
     If true, print the logs for the previous instance of the container in a pod if it exists.
 
+.PP
+\fB\-\-since\fP=0
+    Only return logs newer than a relative duration like 5s, 2m, or 3h. Defaults to all logs. Only one of since\-time / since may be used.
+
+.PP
+\fB\-\-since\-time\fP=""
+    Only return logs after a specific date (RFC3339). Defaults to all logs. Only one of since\-time / since may be used.
+
+.PP
+\fB\-\-tail\fP=\-1
+    Lines of recent log file to display. Defaults to \-1, showing all log lines.
+
+.PP
+\fB\-\-timestamps\fP=false
+    Include timestamps on each line in the log output
+
 
 .SH OPTIONS INHERITED FROM PARENT COMMANDS
 .PP
@@ -133,14 +153,20 @@ Print the logs for a container in a pod. If the pod has only one container, the
 .RS
 
 .nf
-# Return snapshot of ruby\-container logs from pod 123456\-7890.
-$ kubectl logs 123456\-7890 ruby\-container
+# Return snapshot logs from pod nginx with only one container
+$ kubectl logs nginx
+
+# Return snapshot of previous terminated ruby container logs from pod web\-1
+$ kubectl logs \-p \-c ruby web\-1
+
+# Begin streaming the logs of the ruby container in pod web\-1
+$ kubectl logs \-f \-c ruby web\-1
 
-# Return snapshot of previous terminated ruby\-container logs from pod 123456\-7890.
-$ kubectl logs \-p 123456\-7890 ruby\-container
+# Display only the most recent 20 lines of output in pod nginx
+$ kubectl logs \-\-tail=20 nginx
 
-# Start streaming of ruby\-container logs from pod 123456\-7890.
-$ kubectl logs \-f 123456\-7890 ruby\-container
+# Show all logs from pod nginx written in the last hour
+$ kubectl logs \-\-since=1h nginx
 
 .fi
 .RE

docs/user-guide/kubectl/kubectl_logs.md

@@ -47,14 +47,20 @@ kubectl logs [-f] [-p] POD [-c CONTAINER]
 ### Examples
 
 ```
-# Return snapshot of ruby-container logs from pod 123456-7890.
-$ kubectl logs 123456-7890 ruby-container
+# Return snapshot logs from pod nginx with only one container
+$ kubectl logs nginx
 
-# Return snapshot of previous terminated ruby-container logs from pod 123456-7890.
-$ kubectl logs -p 123456-7890 ruby-container
+# Return snapshot of previous terminated ruby container logs from pod web-1
+$ kubectl logs -p -c ruby web-1
 
-# Start streaming of ruby-container logs from pod 123456-7890.
-$ kubectl logs -f 123456-7890 ruby-container
+# Begin streaming the logs of the ruby container in pod web-1
+$ kubectl logs -f -c ruby web-1
+
+# Display only the most recent 20 lines of output in pod nginx
+$ kubectl logs --tail=20 nginx
+
+# Show all logs from pod nginx written in the last hour
+$ kubectl logs --since=1h nginx
 ```
 
 ### Options
@@ -63,7 +69,12 @@ $ kubectl logs -f 123456-7890 ruby-container
   -c, --container="": Container name
   -f, --follow[=false]: Specify if the logs should be streamed.
       --interactive[=true]: If true, prompt the user for input when required. Default true.
+      --limit-bytes=0: Maximum bytes of logs to return. Defaults to no limit.
   -p, --previous[=false]: If true, print the logs for the previous instance of the container in a pod if it exists.
+      --since=0: Only return logs newer than a relative duration like 5s, 2m, or 3h. Defaults to all logs. Only one of since-time / since may be used.
+      --since-time="": Only return logs after a specific date (RFC3339). Defaults to all logs. Only one of since-time / since may be used.
+      --tail=-1: Lines of recent log file to display. Defaults to -1, showing all log lines.
+      --timestamps[=false]: Include timestamps on each line in the log output
 ```
 
 ### Options inherited from parent commands
@@ -98,7 +109,7 @@ $ kubectl logs -f 123456-7890 ruby-container
 
 * [kubectl](kubectl.md)	 - kubectl controls the Kubernetes cluster manager
 
-###### Auto generated by spf13/cobra at 2015-09-10 18:53:03.154570214 +0000 UTC
+###### Auto generated by spf13/cobra at 2015-09-16 18:54:52.319210951 +0000 UTC
 
 <!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
 [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/user-guide/kubectl/kubectl_logs.md?pixel)]()

hack/verify-flags/known-flags.txt

@@ -1,3 +1,4 @@
+
 accept-hosts
 accept-paths
 account-for-pod-resources
@@ -142,6 +143,7 @@ kube-master
 label-columns
 last-release-pr
 legacy-userspace-proxy
+limit-bytes
 load-balancer-ip
 log-flush-frequency
 long-running-request-regexp
@@ -251,6 +253,8 @@ service-node-port-range
 service-node-ports
 service-sync-period
 session-affinity
+since-seconds
+since-time
 show-all
 shutdown-fd
 shutdown-fifo
@@ -286,3 +290,4 @@ www-prefix
 retry_time
 file_content_in_loop
 cpu-cfs-quota
+

pkg/api/deep_copy_generated.go

@@ -1430,6 +1430,33 @@ func deepCopy_api_PodLogOptions(in PodLogOptions, out *PodLogOptions, c *convers
 	out.Container = in.Container
 	out.Follow = in.Follow
 	out.Previous = in.Previous
+	if in.SinceSeconds != nil {
+		out.SinceSeconds = new(int64)
+		*out.SinceSeconds = *in.SinceSeconds
+	} else {
+		out.SinceSeconds = nil
+	}
+	if in.SinceTime != nil {
+		out.SinceTime = new(unversioned.Time)
+		if err := deepCopy_unversioned_Time(*in.SinceTime, out.SinceTime, c); err != nil {
+			return err
+		}
+	} else {
+		out.SinceTime = nil
+	}
+	out.Timestamps = in.Timestamps
+	if in.TailLines != nil {
+		out.TailLines = new(int64)
+		*out.TailLines = *in.TailLines
+	} else {
+		out.TailLines = nil
+	}
+	if in.LimitBytes != nil {
+		out.LimitBytes = new(int64)
+		*out.LimitBytes = *in.LimitBytes
+	} else {
+		out.LimitBytes = nil
+	}
 	return nil
 }
 

pkg/api/helpers.go

@@ -21,6 +21,7 @@ import (
 	"fmt"
 	"reflect"
 	"strings"
+	"time"
 
 	"k8s.io/kubernetes/pkg/api/resource"
 	"k8s.io/kubernetes/pkg/api/unversioned"
@@ -235,3 +236,15 @@ func containsAccessMode(modes []PersistentVolumeAccessMode, mode PersistentVolum
 	}
 	return false
 }
+
+// ParseRFC3339 parses an RFC3339 date in either RFC3339Nano or RFC3339 format.
+func ParseRFC3339(s string, nowFn func() unversioned.Time) (unversioned.Time, error) {
+	if t, timeErr := time.Parse(time.RFC3339Nano, s); timeErr == nil {
+		return unversioned.Time{t}, nil
+	}
+	t, err := time.Parse(time.RFC3339, s)
+	if err != nil {
+		return unversioned.Time{}, err
+	}
+	return unversioned.Time{t}, nil
+}

pkg/api/types.go

@@ -1595,12 +1595,30 @@ type PodLogOptions struct {
 
 	// Container for which to return logs
 	Container string
-
 	// If true, follow the logs for the pod
 	Follow bool
-
 	// If true, return previous terminated container logs
 	Previous bool
+	// A relative time in seconds before the current time from which to show logs. If this value
+	// precedes the time a pod was started, only logs since the pod start will be returned.
+	// If this value is in the future, no logs will be returned.
+	// Only one of sinceSeconds or sinceTime may be specified.
+	SinceSeconds *int64
+	// An RFC3339 timestamp from which to show logs. If this value
+	// preceeds the time a pod was started, only logs since the pod start will be returned.
+	// If this value is in the future, no logs will be returned.
+	// Only one of sinceSeconds or sinceTime may be specified.
+	SinceTime *unversioned.Time
+	// If true, add an RFC3339 or RFC3339Nano timestamp at the beginning of every line
+	// of log output.
+	Timestamps bool
+	// If set, the number of lines from the end of the logs to show. If not specified,
+	// logs are shown from the creation of the container or sinceSeconds or sinceTime
+	TailLines *int64
+	// If set, the number of bytes to read from the server before terminating the
+	// log output. This may not display a complete final line of logging, and may return
+	// slightly more or slightly less than the specified limit.
+	LimitBytes *int64
 }
 
 // PodAttachOptions is the query options to a Pod's remote attach call

pkg/api/v1/conversion_generated.go

@@ -1648,6 +1648,32 @@ func convert_api_PodLogOptions_To_v1_PodLogOptions(in *api.PodLogOptions, out *P
 	out.Container = in.Container
 	out.Follow = in.Follow
 	out.Previous = in.Previous
+	if in.SinceSeconds != nil {
+		out.SinceSeconds = new(int64)
+		*out.SinceSeconds = *in.SinceSeconds
+	} else {
+		out.SinceSeconds = nil
+	}
+	if in.SinceTime != nil {
+		if err := s.Convert(&in.SinceTime, &out.SinceTime, 0); err != nil {
+			return err
+		}
+	} else {
+		out.SinceTime = nil
+	}
+	out.Timestamps = in.Timestamps
+	if in.TailLines != nil {
+		out.TailLines = new(int64)
+		*out.TailLines = *in.TailLines
+	} else {
+		out.TailLines = nil
+	}
+	if in.LimitBytes != nil {
+		out.LimitBytes = new(int64)
+		*out.LimitBytes = *in.LimitBytes
+	} else {
+		out.LimitBytes = nil
+	}
 	return nil
 }
 
@@ -4057,6 +4083,32 @@ func convert_v1_PodLogOptions_To_api_PodLogOptions(in *PodLogOptions, out *api.P
 	out.Container = in.Container
 	out.Follow = in.Follow
 	out.Previous = in.Previous
+	if in.SinceSeconds != nil {
+		out.SinceSeconds = new(int64)
+		*out.SinceSeconds = *in.SinceSeconds
+	} else {
+		out.SinceSeconds = nil
+	}
+	if in.SinceTime != nil {
+		if err := s.Convert(&in.SinceTime, &out.SinceTime, 0); err != nil {
+			return err
+		}
+	} else {
+		out.SinceTime = nil
+	}
+	out.Timestamps = in.Timestamps
+	if in.TailLines != nil {
+		out.TailLines = new(int64)
+		*out.TailLines = *in.TailLines
+	} else {
+		out.TailLines = nil
+	}
+	if in.LimitBytes != nil {
+		out.LimitBytes = new(int64)
+		*out.LimitBytes = *in.LimitBytes
+	} else {
+		out.LimitBytes = nil
+	}
 	return nil
 }
 

pkg/api/v1/deep_copy_generated.go

@@ -1450,6 +1450,33 @@ func deepCopy_v1_PodLogOptions(in PodLogOptions, out *PodLogOptions, c *conversi
 	out.Container = in.Container
 	out.Follow = in.Follow
 	out.Previous = in.Previous
+	if in.SinceSeconds != nil {
+		out.SinceSeconds = new(int64)
+		*out.SinceSeconds = *in.SinceSeconds
+	} else {
+		out.SinceSeconds = nil
+	}
+	if in.SinceTime != nil {
+		out.SinceTime = new(unversioned.Time)
+		if err := deepCopy_unversioned_Time(*in.SinceTime, out.SinceTime, c); err != nil {
+			return err
+		}
+	} else {
+		out.SinceTime = nil
+	}
+	out.Timestamps = in.Timestamps
+	if in.TailLines != nil {
+		out.TailLines = new(int64)
+		*out.TailLines = *in.TailLines
+	} else {
+		out.TailLines = nil
+	}
+	if in.LimitBytes != nil {
+		out.LimitBytes = new(int64)
+		*out.LimitBytes = *in.LimitBytes
+	} else {
+		out.LimitBytes = nil
+	}
 	return nil
 }